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  * The <code>SVGEventListener</code> is used to forward platform specific events

    23  * to an application. The application can implement this interface and, in

    24  * response, dispatch SVG events on an <code>SVGImage</code> object.

    25  * <br />

    26  * <br>

    27  * <br>

    28  * <b>Code example:</b>

    29  * <pre>

    30  *

    31  * // Create an SVGAnimator

    32  * SVGImage map = ...; // See the SVGImage documentation.

    33  * SVGAnimator svgAnimator = SVGAnimator.createAnimator(map);

    34  *

    35  * // Create an SVGEventListener and set it on the animator.

    36  * MIDPSVGEventListener listener = new MIDPSVGEventListener(map, animator);

    37  * svgAnimator.setSVGEventListener(listener);

    38  *

    39  * //

    40  * // SVGEventListener sample implementation. Adds a new

    41  * // circle every time a key is pressed.

    42  * //

    43  * class MIDPSVGEventListener implements SVGEventListener, Runnable {

    44  *      protected SVGDocument svgDocument;

    45  *      protected SVGAnimator svgAnimator;

    46  *      protected Vector addToTree = new Vector();

    47  *

    48  *      public MIDPSVGEventListener(SVGImage svgImage, SVGAnimator animator) {

    49  *          this.svgDocument = svgImage.getDocument();

    50  *          this.svgAnimator = svgAnimator;

    51  *      }

    52  *

    53  *      public void keyPressed(int keyCode) {

    54  *          SVGElement circle = svgDocument.createElementNS(svgNS, "circle");

    55  *          circle.setFloatTrait("cx", ...);

    56  *          circle.setFloatTrait("cy", ...);

    57  *          // ....

    58  *

    59  *          // We synchronized access to the addToTree vector because

    60  *          // it is accessed from different threads. Because we do

    61  *          // no know how fast this runnable is going to be scheduled

    62  *          // by the animator, it is possible that multiple circles

    63  *          // be created before the run() method is invoked. This explain

    64  *          // why we put all the newly created circles in a Vector and why

    65  *          // the run method inserts the current content of the vector

    66  *          // into the SVG document.

    67  *          synchronized (addToTree) {

    68  *             addToTree.addElement(circle);

    69  *          }

    70  *

    71  *          svgAnimator.invokeLater(this);

    72  *      }

    73  *

    74  *      public run() {

    75  *          synchronized (addToTree) {

    76  *              for (int i = 0; i < addToTree.size(); i++) {

    77  *                  svgDocument.getDocumentElement().appendChild(

    78  *                     (SVGElement) addToTree.elementAt(i));

    79  *              }

    80  *              addToTree.clear();

    81  *          }

    82  *      }

    83  * }

    84  * </pre>

    85  *

    86  */

    87 public interface SVGEventListener

    88 {

    89     /**

    90      * Invoked by the SVG implementation when the associated component is

    91      * hidden.

    92      *

    93      * On MIDP, this method is invoked when the

    94      * <code>javax.microedition.lcdui.Canvas.hideNotify</code> method is invoked.

    95      *

    96      * On AWT, this method is invoked when the <code>java.awt.event.ComponentEvent</code>

    97      * with type <code>java.awt.event.ComponentEvent.COMPONENT_HIDDEN</code> is

    98      * invoked on a <code>java.awt.Component</code>'s component listener.

    99      *

   100      */

   101     void hideNotify();

   102 

   103     /**

   104      * Invoked by the SVG implementation when a key was pressed while the

   105      * component associated with the <code>SVGAnimator</code> had focus.

   106      *

   107      * On MIDP, this method is invoked when the

   108      * <code>javax.microedition.lcdui.Canvas.keyPressed()</code> method is

   109      * invoked.

   110      *

   111      * On AWT, this method is invoked when the

   112      * <code>java.awt.event.KeyListener.keyPressed()</code> method is invoked on

   113      * a <code>java.awt.Component</code>'s key listener.

   114      *

   115      * @param keyCode the code of the key that was pressed. For MIDP, the code

   116      * is the same as for the <code>javax.microedition.lcdui.Canvas</code>

   117      * <code>keyPressed</code> <code>keyCode</code> argument.  For AWT, the code

   118      * is the same as in the <code>java.awt.event.KeyEvent.getKeyCode()</code>

   119      * method.

   120      */

   121     void keyPressed(int keyCode);

   122 

   123     /**

   124      * Invoked by the SVG implementation when a key was released while the

   125      * component associated with the <code>SVGAnimator</code> had focus.

   126      *

   127      * On MIDP, this method is invoked when the

   128      * <code>javax.microedition.lcdui.Canvas.keyReleased()</code> method is

   129      * invoked.

   130      *

   131      * On AWT, this method is invoked when the

   132      * <code>java.awt.event.KeyListener.keyReleased()</code> method is invoked on

   133      * a <code>java.awt.Component</code>'s key listener.

   134      *

   135      * @param keyCode the code of the key that was pressed. For MIDP, the code

   136      * is the same as for the <code>javax.microedition.lcdui.Canvas</code>

   137      * <code>keyReleased</code> <code>keyCode</code> argument.  For AWT, the code

   138      * is the same as in the <code>java.awt.event.KeyEvent.getKeyCode()</code>

   139      * method.

   140      */

   141     void keyReleased(int keyCode);

   142 

   143     /**

   144      * Invoked by the SVG implementation when the pointer device (if any), is

   145      * pressed over the component associated with the <code>SVGAnimator</code>.

   146      *

   147      * On MIDP, this method is invoked when the

   148      * <code>javax.microedition.lcdui.Canvas.pointerPressed()</code> method is

   149      * invoked. Note that pointer events are only supported on MIDP if the

   150      * platform supports them, as defined by the

   151      * <code>Canvas.hasPointerEvents</code> method.

   152      *

   153      * On AWT, this method is invoked when the

   154      * <code>java.awt.event.MouseListener.mousePressed()</code> method is invoked on

   155      * a <code>java.awt.Component</code>'s mouse listener.

   156      *

   157      * @param x the x-axis coordinate, in the target component's space (i.e.,

   158      * relative to the upper left corner of the component associated with the

   159      * <code>SVGAnimator</code>.  On MIDP, this is the same value as passed to the

   160      * <code>javax.microedition.midp.Canvas.pointerPressed()</code> method.  On

   161      * AWT, this is the same value as returned from the

   162      * <code>java.awt.event.MouseEvent.getX()</code> method.

   163      *

   164      * @param y the y-axis coordinate, in the target component's space (i.e.,

   165      * relative to the upper left corner of the component associated with the

   166      * <code>SVGAnimator</code>.  On MIDP, this is the same value as passed to the

   167      * <code>javax.microedition.midp.Canvas.pointerPressed()</code> method.  On

   168      * AWT, this is the same value as returned from the

   169      * <code>java.awt.event.MouseEvent.getY()</code> method.

   170      */

   171     void pointerPressed(int x, int y);

   172 

   173     /**

   174      * Invoked by the SVG implementation when the pointer device (if any), is

   175      * released over the component associated with the <code>SVGAnimator</code>.

   176      *

   177      * On MIDP, this method is invoked when the

   178      * <code>javax.microedition.lcdui.Canvas.pointerReleased()</code> method is

   179      * invoked. Note that pointer events are only supported on MIDP if the

   180      * platform supports them, as defined by the

   181      * <code>Canvas.hasPointerEvents</code> method.

   182      *

   183      * On AWT, this method is invoked when the

   184      * <code>java.awt.event.MouseListener.mouseReleased()</code> method is invoked on

   185      * a <code>java.awt.Component</code>'s mouse listener.

   186      *

   187      * @param x the x-axis coordinate, in the target component's space (i.e.,

   188      * relative to the upper left corner of the component associated with the

   189      * <code>SVGAnimator</code>.  On MIDP, this is the same value as passed to the

   190      * <code>javax.microedition.midp.Canvas.pointerReleased()</code> method.  On

   191      * AWT, this is the same value as returned from the

   192      * <code>java.awt.event.MouseEvent.getX()</code> method.

   193      *

   194      * @param y the y-axis coordinate, in the target component's space (i.e.,

   195      * relative to the upper left corner of the component associated with the

   196      * <code>SVGAnimator</code>.  On MIDP, this is the same value as passed to the

   197      * <code>javax.microedition.midp.Canvas.pointerReleased()</code> method.  On

   198      * AWT, this is the same value as returned from the

   199      * <code>java.awt.event.MouseEvent.getY()</code> method.

   200      */

   201     void pointerReleased(int x, int y);

   202 

   203     /**

   204      * Invoked by the SVG implementation when the associated component is

   205      * shown.

   206      *

   207      * On MIDP, this method is invoked when the

   208      * <code>javax.microedition.lcdui.Canvas.showNotify</code> method is invoked.

   209      *

   210      * On AWT, this method is invoked when the <code>java.awt.event.ComponentEvent</code>

   211      * with type <code>java.awt.event.ComponentEvent.COMPONENT_SHOWN</code> is

   212      * invoked on a <code>java.awt.Component</code>'s component listener.

   213      *

   214      */

   215     void showNotify();

   216 

   217     /**

   218      * Invoked by the SVG implementation when the associated component is

   219      * resized.

   220      *

   221      * On MIDP, this method is invoked when the

   222      * <code>javax.microedition.lcdui.Canvas.sizeChanged</code> method is invoked.

   223      *

   224      * On AWT, this method is invoked when the <code>java.awt.event.ComponentEvent</code>

   225      * with type <code>java.awt.event.ComponentEvent.COMPONENT_RESIZED</code> is

   226      * invoked on a <code>java.awt.Component</code>'s component listener.

   227      *

   228      * @param width the new component width.

   229      * @param height the new component height.

   230      */

   231     void sizeChanged(int width, int height);

   232 }

   233