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)

Since:
JDE 4.6.0
See Also:
ScalableImage, Document

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:
JDE 4.6.0
Method Detail

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:
JDE 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
Since:
JDE 4.6.0
See Also:
ExternalResourceHandler

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:
JDE 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:
JDE 4.6.0

getDocument

public Document getDocument()

Returns the associated Document.

Returns:
the associated Document.
Since:
JDE 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.

Overrides:
getViewportHeight in class ScalableImage
Returns:
the current height of this ScalableImage.
Since:
JDE 4.6.0
See Also:
setViewportHeight(int)

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.

Overrides:
getViewportWidth in class ScalableImage
Returns:
the current width of this ScalableImage.
Since:
JDE 4.6.0
See Also:
setViewportWidth(int)

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:
JDE 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.

Overrides:
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
Since:
JDE 4.6.0
See Also:
ExternalResourceHandler

setViewportHeight

public void setViewportHeight(int height)

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

Overrides:
setViewportHeight in class ScalableImage
Parameters:
height - the new height to be set.
Throws:
IllegalArgumentException - if height is negative.
Since:
JDE 4.6.0
See Also:
getViewportHeight()

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.

Overrides:
setViewportWidth in class ScalableImage
Parameters:
width - the new width to be set.
Throws:
IllegalArgumentException - if width is negative.
Since:
JDE 4.6.0
See Also:
getViewportWidth()



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.