javax.microedition.m2g
Class ScalableImage

java.lang.Object
  javax.microedition.m2g.ScalableImage

Direct Known Subclasses:

SVGImage

public abstract class ScalableImage
extends Object

This class models images in vector format, such as the Scalable Vector Graphics (SVG) image format. Therefore, it is required that all classes representing "scalable" images extend this class.

See Also:

SVGImage

Since:

BlackBerry API 4.6.0

Constructor Summary
protected	ScalableImage() Constructor.

Method Summary
static ScalableImage	createImage(InputStream stream, ExternalResourceHandler handler) This method creates and loads a ScalableImage (e.g.
static ScalableImage	createImage(String URL, ExternalResourceHandler handler) This method creates and loads a ScalableImage (e.g.
abstract int	getViewportHeight() This method returns the ScalableImage's viewport height.
abstract int	getViewportWidth() This method returns the ScalableImage's viewport width.
abstract void	requestCompleted(String URI, InputStream resourceData) Once the requested external resource is available, the application forwards this information (resourceData) to the SVG engine.
abstract void	setViewportHeight(int height) This method sets the new (viewport) height of this ScalableImage.
abstract void	setViewportWidth(int width) This method sets the new (viewport) width of this ScalableImage.

Methods inherited from class java.lang.Object

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

Constructor Detail

ScalableImage

protected ScalableImage()

Constructor.

Since:

BlackBerry API 4.6.0

Method Detail

createImage

public static ScalableImage createImage(InputStream stream,
                                        ExternalResourceHandler handler)
                                 throws IOException

This method creates and loads a ScalableImage (e.g. SVG) from the specified stream. A ScalableImage can only be rendered using the render() method in the ScalableGraphics context.The image size is determined by the content specification (eg: width/height attributes on root SVG element). The default viewport size of 100-by-100 pixels is used when the size is unspecified. This method will throw an exception when the image is in error. For SVG document, the document is in error when:

• the SVG document does not conform to the XML 1.0 specification
• an element has an attribute or property value which is not permissible according to the SVG specification
• the required or mandatory attributes according to the SVG specification are missing
• the document contains circular references on the <use> element
• the document contains <image> element(s) with local references
• the document contains elements with duplicate Id's
• the document contains animation(s) in error

If an handler is specified, the engine will invoke it for any external resource referenced in the document. However, please note that data URIs (for ex: base64 encoded images like <image xlink:href="data:image/png;base64,/9j/4AAQ..."/>) are required to be decoded by the engine, and therefore the handlerwill not be invoked in such cases. All these requests must occur before createImage returns, and the engine must only make one call if there exist multiple resources with the same URI. If the handler is set to null, the ScalableImage will try to load images automatically using the engine's default implementation, but might not be able to load all of them. For example, if the ScalableImage is loaded from a file in a Jar file, the implementation will not be able to load images that have relative URIs (ex; <image xlink:href="myImage.png" />). If the handler is not able to locate a requested resource, it informs the SVG engine by calling the requestCompleted method with null for resourceData.

Note that the handler is also called when the xlink:href attribute on <image> is set or changed by the application, but the call is made only when the element is hooked into the document tree i.e. when the ancestors go all the way up to the root <svg> element. There are two cases:

• When changing the xlink:href attribute of an existing <image> element that is already hooked or part of the tree.
• When creating a new <image>, setting its xlink:href and hooking it to the document tree.

Parameters:

stream - The stream from which the SVG content should be read.

handler - implementation of the ExternalResourceHandler interface

Returns:

the loaded ScalableImage.

Throws:

IOException - if an error occurs while loading the content.

NullPointerException - if stream is null.

See Also:

ExternalResourceHandler

Since:

BlackBerry API 4.6.0

createImage

public static ScalableImage createImage(String URL,
                                        ExternalResourceHandler handler)
                                 throws IOException

This method creates and loads a ScalableImage (e.g. SVG) with the specified URI. A ScalableImage can only be rendered using the render() method in the ScalableGraphics context.The image size is determined by the content specification (eg: width/height attributes on root SVG element). The default viewport size of 100-by-100 pixels is used when the size is unspecified. This method will throw an exception when the image is in error. For SVG document, the document is in error when:

• the SVG document does not conform to the XML 1.0 specification
• an element has an attribute or property value which is not permissible according to the SVG specification
• the required or mandatory attributes according to the SVG specification are missing
• the document contains circular references on the <use> element
• the document contains <image> element(s) with local references
• the document contains elements with duplicate Id's
• the document contains animation(s) in error

If an handler is specified, the engine will invoke it for any external resource referenced in the document. However, please note that data URIs (for ex: base64 encoded images like <image xlink:href="data:image/png;base64,/9j/4AAQ..."/>) are required to be decoded by the engine, and therefore the handler will not be invoked in such cases. All these requests must occur before createImage returns, and the engine must only make one call if there exist multiple resources with the same URI. If the handler is set to null, the ScalableImage will try to load images automatically using the engine's default implementation, but might not be able to load all of them. For example, if the ScalableImage is loaded from a file in a Jar file, the implementation will not be able to load images that have relative URIs (ex: <image xlink:href="myImage.png" />). If the handler is not able to locate a requested resource, it informs the SVG engine by calling the requestCompleted method with null for resourceData.

Note that the handler is also called when the xlink:href attribute on <image> is set or changed by the application, but the call is made only when the element is hooked into the document tree i.e. when the ancestors go all the way up to the root <svg> element. There are two cases:

• When changing the xlink:href attribute of an existing <image> element that is already hooked or part of the tree.
• When creating a new <image>, setting its xlink:href and hooking it to the document tree.

If the platform implementation supports the JSR-75 FileConnection, then the file: URLs as used by JSR-75 shall be supported and the images are loaded from files identified by this locator. This can be used to load possible DRM protected image files from the file system.

Parameters:

URL - A string in URL syntax that identifies the image source.

handler - implementation of the ExternalResourceHandler interface

Returns:

the loaded ScalableImage

Throws:

IOException - if an error occurs while loading the SVG content.

NullPointerException - if URL is null.

IllegalArgumentException - if the specified locator is of unsupported type.

SecurityException - if the application does not have the privilege rights to access the contents of this resource.

See Also:

ExternalResourceHandler

Since:

BlackBerry API 4.6.0

setViewportWidth

public abstract void setViewportWidth(int width)

This method sets the new (viewport) width of this ScalableImage. The viewport is the area where the ScalableImage is rendered. Any parts of the viewport that lie outside the boundaries of the target clipping rectangle are clipped. The viewport upper left corner (x, y) is given relative to the upper left corner of the target rendering surface.

Parameters:

width - the new width to be set.

Throws:

IllegalArgumentException - if width is negative.

See Also:

ScalableImage.getViewportWidth()

Since:

BlackBerry API 4.6.0

setViewportHeight

public abstract void setViewportHeight(int height)

This method sets the new (viewport) height of this ScalableImage.

Parameters:

height - the new height to be set.

Throws:

IllegalArgumentException - if height is negative.

See Also:

ScalableImage.getViewportHeight()

Since:

BlackBerry API 4.6.0

getViewportWidth

public abstract int getViewportWidth()

This method returns the ScalableImage's viewport width. The initial viewport width is taken from the "width" value specified in the Scalable Image. The value returned is always in pixels. If the specified width is defined in percentages, the values are mapped to the default view port size of 100x100. If the viewport width is explicitly changed by the application, then the percentages are ignored and the content is made to fit to this new viewport width.

Returns:

the current width of this ScalableImage.

See Also:

ScalableImage.setViewportWidth(int)

Since:

BlackBerry API 4.6.0

getViewportHeight

public abstract int getViewportHeight()

This method returns the ScalableImage's viewport height. The initial viewport height is taken from the "height" value specified in the Scalable Image. The value returned is always in pixels. If the specified height is defined in percentages, the values are mapped to the default view port size of 100x100. If the viewport height is explicitly changed by the application, then the percentages are ignored and the content is made to fit to this new viewport height.

Returns:

the current height of this ScalableImage.

See Also:

ScalableImage.setViewportHeight(int)

Since:

BlackBerry API 4.6.0

requestCompleted

public abstract void requestCompleted(String URI,
                                      InputStream resourceData)
                               throws IOException

Once the requested external resource is available, the application forwards this information (resourceData) to the SVG engine. If this method is called a second time for a same URL of a same SVGImage, the engine will replace the current resource data with the new one. Note: Setting null for resourceData indicates that the requested resource could not be fetched by the ResourceHandler or application, and in this event the SVG engine will not make further attempts to load this resource.

Parameters:

URI - URI that was requested through requestExternalResource

resourceData - inputstream containing the external resource

Throws:

IOException - if an error occurs while loading the resource.

NullPointerException - if URL is null.

See Also:

ExternalResourceHandler

Since:

BlackBerry API 4.6.0