javax.microedition.m2g
Class ScalableImage

java.lang.Object
  extended by 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:

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:

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:

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:

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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.