javax.microedition.m2g
Class SVGImage

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

public class SVGImage
extends ScalableImage

This class represents an SVG image conforming to the W3C SVG Tiny 1.1 Profile. Applications can access the Document associated with this SVGImage using getDocument method. Using the Document class, it is possible to interact with the content and perform operations such as zoom, pan, and rotate apart from various other functions. The event dispatching methods as described in this class must be used for dispatching user specific events to the underlying SVG engine. Note that the DOM event flow resulting from invoking methods such as focusOn or dispatchMouseEvent are limited to the at-target and bubble phase of the DOM Level 2 event flow.

The width and height values specified in the SVGImage are only used to compute the initial viewport width/height. It is also important to note that according to the SVG 1.1 specification, if viewBox is not defined, then the preserveAspectRatio attribute is ignored. Therefore, the contents should not be scaled if there is no viewBox defined.

Note: If the application does not have the necessary privilege rights to access this (SVG) content, a SecurityException may be thrown by the underlying implementation. This is applicable to all the tree navigation (see Node) and trait acessor methods (see SVGElement). Features such as zooming, panning and playing of animations will not be affected.

Here is the list of events supported in this specification:

Events	Description
"DOMFocusIn"	Occurs when the element comes into focus.
"DOMFocusOut"	Occurs when an element goes out of focus.
"DOMActivate"	Occurs when an element is activated, for instance, through a keypress (select)
"click"	Occurs when the pointing device button is clicked over the SVG content (or particular SVGElement)

See Also:

ScalableImage, Document

Since:

BlackBerry API 4.6.0

Constructor Summary
protected	SVGImage() Constructor.

Method Summary
void	activate() This method is used to dispatch an "DOMActivate" event to the document.
static SVGImage	createEmptyImage(ExternalResourceHandler handler) This method creates and loads an empty SVGImage (skeleton) that can be used to programatically construct a simple SVG image.
void	dispatchMouseEvent(String type, int x, int y) This method is used to dispatch a mouse event of the specified type to the document.
void	focusOn(SVGElement element) This method triggers a "DOMFocusIn" event with the specified element as the event target.
Document	getDocument() Returns the associated Document.
int	getViewportHeight() This method returns the ScalableImage's viewport height.
int	getViewportWidth() This method returns the ScalableImage's viewport width.
void	incrementTime(float seconds) Increments the animation or media timeline for this SVGImage (in seconds).
void	requestCompleted(String URI, InputStream resourceData) Once the requested external resource is available, the application forwards this information (resourceData) to the SVG engine.
void	setViewportHeight(int height) This method sets the new (viewport) height of this ScalableImage.
void	setViewportWidth(int width) This method sets the new (viewport) width of this ScalableImage.

Methods inherited from class javax.microedition.m2g.ScalableImage

createImage, createImage

Methods inherited from class java.lang.Object

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

Constructor Detail

SVGImage

protected SVGImage()

Constructor.

Since:

BlackBerry API 4.6.0

Method Detail

getDocument

public Document getDocument()

Returns the associated Document.

Returns:

the associated Document.

Since:

BlackBerry API 4.6.0

createEmptyImage

public static SVGImage createEmptyImage(ExternalResourceHandler handler)

This method creates and loads an empty SVGImage (skeleton) that can be used to programatically construct a simple SVG image. Note: A root <svg> element with default viewport size of 100x100 is also created inside this method.

If an handler is specified, the engine will invoke it for any external resource referenced in the document. If the handler is set to null, the SVGImage will try to load images automatically using the engine default implementation,but might not be able to load all of them.

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:

handler - implementation of the ExternalResourceHandler interface

Returns:

an empty SVGImage

See Also:

ExternalResourceHandler

Since:

BlackBerry API 4.6.0

dispatchMouseEvent

public void dispatchMouseEvent(String type,
                               int x,
                               int y)
                        throws DOMException

This method is used to dispatch a mouse event of the specified type to the document. The mouse position is given as screen coordinates x, y. If the x, y values are outside the viewport area or no target is available for the x, y coordinates, the event is not dispatched. Note that when a "click" event is dispatched, a "DOMActivate" is automatically dispatched by the underlying implementation. The only required mouse event type is "click". Implementations may support more event types than click. However, using these additional event types may not work in all conformant JSR 226 1.0 implementations. Therefore, if an unsupported type is specified, a DOMException with error code NOT_SUPPORTED_ERR is thrown.

Parameters:

type - the type of mouse event.

x - the x location of the mouse/pointer in viewport coordinate system.

y - the y location of the mouse/pointer in viewport coordinate system.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR: if the event type is not supported.

NullPointerException - if type is null.

IllegalArgumentException - if the x or y values are negative.

Since:

BlackBerry API 4.6.0

activate

public void activate()

This method is used to dispatch an "DOMActivate" event to the document. The element that has focus is activated, which means that a "DOMActivate" event with the the currently focused element as target is dispatched. If no element has focus, this method does not do anything and no event is dispatched.

Since:

BlackBerry API 4.6.0

focusOn

public void focusOn(SVGElement element)
             throws DOMException

This method triggers a "DOMFocusIn" event with the specified element as the event target. That element becomes the element with focus. This method also triggers a "DOMFocusOut" event with the element which previous had focus as target. When the activate method is called, a "DOMActivate" event is triggered with the currently focused element as the target. The initial focus is always null and setting null will remove the current focus.

Parameters:

element - the element to set the focus on.

Throws:

DOMException - with error code WRONG_DOCUMENT_ERR: if invalid element is passed (for ex: an element that does not belong to this document).

Since:

BlackBerry API 4.6.0

incrementTime

public void incrementTime(float seconds)

Increments the animation or media timeline for this SVGImage (in seconds). As the name implies, this method is intended to move only forward in the timeline and typically should be used to animate SVG content when the SVGAnimator class in not used. Setting negative values will throw an Exception.
As the new time is applied to the document, animation events (beginEvent, endEvent, repeatEvent) are dispatched by the implementation.(see org.w3c.dom.events.TimeEvent).
It is important to note that setting large increments of time would result in skipping parts of the animation as per the SVG animation model.

Parameters:

seconds - the value of time to increment in seconds.

Throws:

IllegalArgumentException - if the specified time seconds is negative.

Since:

BlackBerry API 4.6.0

setViewportWidth

public 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.

Specified by:

setViewportWidth in class ScalableImage

Parameters:

width - the new width to be set.

Throws:

IllegalArgumentException - if width is negative.

See Also:

SVGImage.getViewportWidth()

Since:

BlackBerry API 4.6.0

setViewportHeight

public void setViewportHeight(int height)

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

Specified by:

setViewportHeight in class ScalableImage

Parameters:

height - the new height to be set.

Throws:

IllegalArgumentException - if height is negative.

See Also:

SVGImage.getViewportHeight()

Since:

BlackBerry API 4.6.0

getViewportWidth

public 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.

Specified by:

getViewportWidth in class ScalableImage

Returns:

the current width of this ScalableImage.

See Also:

SVGImage.setViewportWidth(int)

Since:

BlackBerry API 4.6.0

getViewportHeight

public 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.

Specified by:

getViewportHeight in class ScalableImage

Returns:

the current height of this ScalableImage.

See Also:

SVGImage.setViewportHeight(int)

Since:

BlackBerry API 4.6.0

requestCompleted

public 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.

Specified by:

requestCompleted in class ScalableImage

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