1 /*

     2 * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 

    19 package javax.microedition.m2g;

    20 

    21 //--------------------------------------------------

    22 //Imports

    23 //--------------------------------------------------

    24 import java.io.*;

    25 import java.io.InputStream;

    26 import org.w3c.dom.Document;

    27 import org.w3c.dom.DOMException;

    28 import org.w3c.dom.svg.SVGElement;

    29 import com.nokia.microedition.m2g.M2GSVGImage;

    30 

    31 /**

    32 * This class represents an SVG image conforming to the W3C SVG Tiny 1.1 Profile. Applications can access the Document

    33 * associated with this SVGImage using <code>getDocument</code> method. Using the <code>Document</code> class,

    34 * it is possible to interact with the content and perform operations such as zoom, pan, and rotate

    35 * apart from various other functions. The event dispatching methods as described

    36 * in this class must be used for dispatching user specific events to the underlying SVG engine.

    37 *

    38 * <p>

    39 * The width and height values specified in the SVGImage are only used to compute the initial viewport width/height.

    40 * It is also important to note that according to the SVG 1.1 specification, if viewBox is not defined, then

    41 * the preserveAspectRatio attribute is ignored. Therefore, the contents should not be scaled if there is no

    42 * viewBox defined.

    43 * </p>

    44 * <p><b>Note:</b> If the application does not have the necessary privilege rights to access this (SVG)

    45 * content, a SecurityException may be thrown by the underlying implementation. This is applicable

    46 * to all the tree navigation (see {@link org.w3c.dom.Node Node}) and trait acessor methods (see {@link org.w3c.dom.svg.SVGElement SVGElement}).

    47 * Features such as zooming, panning and playing of animations will not be affected.

    48 * <p>

    49 * Here is the list of events supported in this specification:

    50 * <p>

    51 * <table  cellpadding="2" cellspacing="2" border="1"

    52  *  style="border-collapse: collapse;">

    53  *   <tbody>

    54  *     <tr>

    55  *       <th width="150" valign="top" bgcolor="#999999"><b>Events<br>

    56  *       </b> </th>

    57  *       <th valign="top" bgcolor="#999999"><b>Description<br>

    58  *       </b> </th>

    59  *     </tr>

    60  *     <tr>

    61  *       <td valign="top"> <b>"DOMFocusIn"</b><br>

    62  *       </td>

    63  *       <td valign="top"> Occurs when the element comes into focus.<br>

    64  *       </td>

    65  *     </tr>

    66  *     <tr>

    67  *       <td valign="top"> <b>"DOMFocusOut"</b><br>

    68  *       </td>

    69  *       <td valign="top"> Occurs when an element goes out of focus.<br>

    70  *       </td>

    71  *     </tr>

    72  *     <tr>

    73  *       <td valign="top"> <b>"DOMActivate"</b><br>

    74  *       </td>

    75  *       <td valign="top"> Occurs when an element is activated, for instance, through a keypress (select)<br>

    76  *       </td>

    77  *     </tr>

    78  *     <tr>

    79  *       <td valign="top"> <b>"click"</b><br>

    80  *       </td>

    81  *       <td valign="top"> Occurs when the pointing device button is clicked over the SVG content (or particular SVGElement) <br>

    82  *       </td>

    83  *     </tr>

    84  *   </tbody>

    85  * </table>

    86 * @see      javax.microedition.m2g.ScalableImage

    87 * @see      org.w3c.dom.Document

    88 */

    89 

    90 public class SVGImage extends ScalableImage

    91 {

    92     //--------------------------------------------------

    93     // VARIABLES

    94     //--------------------------------------------------

    95     private M2GSVGImage iImg = null;

    96 

    97     /**

    98      * Constructor

    99      */

   100     protected SVGImage()

   101     {

   102         super();

   103     }

   104 

   105     /**

   106      * This method is used to dispatch an "DOMActivate" event to the document.

   107      * The element that has focus is activated, which means that a

   108      * "DOMActivate" event with the the currently focused element as target is

   109      * dispatched. If no element has focus, this method does not do anything

   110      * and no event is dispatched.

   111      */

   112     public void activate()

   113     {

   114         iImg.activate();

   115     }

   116 

   117     /**

   118      * This method creates and loads an empty SVGImage (skeleton) that can be used to

   119      * programatically construct a simple SVG image. Note: A root <svg> element

   120      * with default viewport size of 100x100 is also created inside this method.

   121      *

   122      * <p>If an handler is specified, the engine will invoke it for any external resource

   123      * referenced in the document. If the handler is set to null, the SVGImage will try to

   124      * load images automatically using the engine default implementation,but might not be

   125      * able to load all of them.</p>

   126      *

   127      * <p>Note that the <code>handler</code> is also called when the xlink:href attribute on

   128      * <image> is set or changed by the application, but the call is made only when the

   129      * element is hooked into the document tree i.e. when the ancestors go all the way up to

   130      * the root <svg> element. There are two cases:

   131      * <ul>

   132      * <li>When changing the xlink:href attribute of an existing &lt;image&gt; element that is already hooked or part of the tree.</li>

   133      * <li>When creating a new &lt;image&gt;, setting its xlink:href and hooking it to the document tree.</li>

   134      * </ul>

   135      * </p>

   136      *

   137      * @param handler implementation of the ExternalResourceHandler interface

   138      * @see      javax.microedition.m2g.ExternalResourceHandler

   139      *

   140      * @return an empty SVGImage

   141      */

   142     public static SVGImage createEmptyImage(ExternalResourceHandler handler)

   143     {

   144         M2GSVGImage image = M2GSVGImage.buildEmptyImage(handler);

   145         if (image == null)

   146         {

   147             throw new NullPointerException();

   148         }

   149         SVGImage proxy = new SVGImage();

   150         proxy.iImg = image;

   151         return proxy;

   152     }

   153 

   154     /**

   155      * @see javax.microedition.m2g.ScalableImage

   156      */

   157     public static ScalableImage createImage(

   158         InputStream stream, ExternalResourceHandler handler) throws IOException

   159     {

   160         M2GSVGImage image = M2GSVGImage.buildImage(stream, handler, null, null);

   161         if (image == null)

   162         {

   163             throw new NullPointerException();

   164         }

   165         SVGImage proxy = new SVGImage();

   166         proxy.iImg = image;

   167         return proxy;

   168     }

   169 

   170     /**

   171      * @see javax.microedition.m2g.ScalableImage

   172      */

   173     public static ScalableImage createImage(

   174         String url, ExternalResourceHandler handler) throws IOException

   175     {

   176         M2GSVGImage image = M2GSVGImage.buildImage(url, handler);

   177         if (image == null)

   178         {

   179             throw new NullPointerException();

   180         }

   181         SVGImage proxy = new SVGImage();

   182         proxy.iImg = image;

   183         return proxy;

   184     }

   185 

   186     /**

   187      * This method is used to dispatch a mouse event of the specified <code>type</code> to the

   188      * document. The mouse position is given as screen coordinates <code>x, y</code>. If the

   189      * x, y values are outside the viewport area or no target is available for the x, y

   190      * coordinates, the event is not dispatched. Note that when a "click" event is dispatched,

   191      * a "DOMActivate" is automatically dispatched by the underlying implementation. The only

   192      * required mouse event type is "click". Therefore, if an unsupported type is specified,

   193      * a DOMException with error code NOT_SUPPORTED_ERR is thrown.

   194      *

   195      *

   196      * @param type the type of mouse event.

   197      * @param x the x location of the mouse/pointer in viewport coordinate

   198      *        system.

   199      * @param y the y location of the mouse/pointer in viewport coordinate

   200      *        system.

   201      * @throws DOMException with error code NOT_SUPPORTED_ERR: if the event <code>type</code> is not supported.

   202      * @throws NullPointerException if <code>type</code> is null.

   203      * @throws IllegalArgumentException if the x or y values are negative.

   204      *

   205      */

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

   207     {

   208         iImg.dispatchMouseEvent(type, x, y);

   209     }

   210 

   211     /**

   212      * Returns the associated <code>Document</code>.

   213      * @return the associated <code>Document</code>.

   214      */

   215     public Document getDocument()

   216     {

   217         return iImg.getDocument();

   218     }

   219 

   220     /**

   221      * @see javax.microedition.m2g.ScalableImage

   222      */

   223     public int getViewportHeight()

   224     {

   225         return iImg.getViewportHeight();

   226     }

   227 

   228     /**

   229      * @see javax.microedition.m2g.ScalableImage

   230      */

   231     public int getViewportWidth()

   232     {

   233         return iImg.getViewportWidth();

   234     }

   235 

   236     /**

   237      * This method triggers a "DOMFocusIn" event with the specified element as

   238      * the event target. That element becomes the element with focus. This

   239      * method also triggers a "DOMFocusOut" event with the element which

   240      * previous had focus as target. When the activate method is called, a

   241      * "DOMActivate" event is triggered with the currently focused element as

   242      * the target. The initial focus is always <code>null</code> and setting

   243      * <code>null</code> will remove the current focus.

   244      *

   245      * @param element the element to set the focus on.

   246      * @throws DOMException with error code WRONG_DOCUMENT_ERR: if invalid element is passed (for

   247      * ex: an element that does not belong to this document).

   248      */

   249     public void focusOn(SVGElement element)  throws DOMException

   250     {

   251         iImg.focusOn(element);

   252     }

   253 

   254     /**

   255      * Increments the animation or media timeline for this SVGImage (in seconds). As the name

   256      * implies, this method is intended to move only forward in the timeline and typically should be used

   257      * to animate SVG content when the SVGAnimator class in not used. Setting negative values will throw

   258      * an Exception. It is important to note that setting large increments of time would result in

   259      * skipping parts of the animation as per the SVG animation model.

   260      *

   261      * @param seconds the value of time to increment in seconds.

   262      * @throws IllegalArgumentException if the specified time is negative.

   263      */

   264     public void incrementTime(float seconds)

   265     {

   266         iImg.incrementTime(seconds);

   267     }

   268 

   269     /**

   270      * @see javax.microedition.m2g.ScalableImage

   271      */

   272     public void requestCompleted(

   273         String URI, InputStream resourceData) throws IOException

   274     {

   275         iImg.requestCompleted(URI, resourceData);

   276     }

   277 

   278     /**

   279      * @see javax.microedition.m2g.ScalableImage

   280      */

   281     public void setViewportHeight(int height)

   282     {

   283         iImg.setViewportHeight(height);

   284     }

   285 

   286     /**

   287      * @see javax.microedition.m2g.ScalableImage

   288      */

   289     public void setViewportWidth(int width)

   290     {

   291         iImg.setViewportWidth(width);

   292     }

   293 }

   294