1 /*

     2  * Copyright (c) 2009 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:  Public abstract class defining the

    15  *               interface for MIDP Canvas Graphics Item.

    16  *

    17  */

    18 

    19 package com.nokia.mid.ui;

    20 

    21 import java.util.Enumeration;

    22 import javax.microedition.lcdui.Canvas;

    23 import javax.microedition.lcdui.CustomItem;

    24 import javax.microedition.lcdui.Graphics;

    25 

    26 import com.nokia.mid.ui.CanvasItem;

    27 import com.nokia.mid.ui.CanvasGraphicsItemPainter;

    28 

    29 import com.nokia.mj.impl.rt.legacy.NativeError;

    30 import com.nokia.mj.impl.rt.legacy.ToolkitInvoker;

    31 import com.nokia.mj.impl.rt.support.Finalizer;

    32 

    33 /**

    34  * <P>

    35  * A <code>CanvasGraphicsItem</code> is a drawable component that is used with a

    36  * parent object; with <code>Canvas</code>. The <code>CanvasGraphicsItem</code>

    37  * may be added to and removed from <code>Canvas</code> through

    38  * <code>setParent</code> method.

    39  * </P>

    40  *

    41  * <P>

    42  * Parent for <code>CanvasGraphicsItem</code> must be set, through

    43  * <code>setParent</code> method, before other methods are called and change the

    44  * state or parameters of <code>CanvasGraphicsItem</code>.

    45  * </P>

    46  *

    47  * <P>

    48  * The implementation presents the <code>CanvasGraphicsItem</code> with the same

    49  * draw capabilities as <code>Canvas</code> has. See <a

    50  * href="Graphics.html">Graphics</a> for drawing options.

    51  * </P>

    52  *

    53  * <P>

    54  * <code>CanvasGraphicsItem</code> does not support DSA over its area. Playing

    55  * video or using camera over <code>CanvasGraphicsItem</code> area can lead to

    56  * artifacts on screen.

    57  * </P>

    58  *

    59  * <P>

    60  * <code>CanvasGraphicsItem</code> does not support touch input. Pointer events

    61  * are delivered to parent object from the area of the visible

    62  * <code>CanvasGraphicsItem</code>.

    63  * </P>

    64  *

    65  * <P>

    66  * Visibility of <code>CanvasGraphicsItem</code> is set through

    67  * <code>setVisible()</code>. The default visbility is set to false. Changing

    68  * parent does not affect the visibility status.

    69  * </P>

    70  *

    71  * <P>

    72  * The <code>CanvasGraphicsItem</code> cannot have focus.

    73  * </P>

    74  *

    75  * @since 1.4

    76  */

    77 public abstract class CanvasGraphicsItem

    78         extends CanvasItem

    79 {

    80     // Private data

    81 

    82     // Native handle

    83     int iHandle;

    84 

    85     // LCDUI Toolkit invoker object.

    86     ToolkitInvoker iToolkitInvoker;

    87 

    88     // LCDUI Toolkit object.

    89     Object iToolkit;

    90 

    91     //Object finalizer

    92     private Finalizer mFinalizer;

    93 

    94     private com.nokia.mid.ui.CanvasGraphicsItemPainter iItemPainter;

    95 

    96     /**

    97      * Creates a new <code>CanvasGraphicsItem</code> object with the given

    98      * initial size.

    99      *

   100      * @param width

   101      *            width in pixels

   102      * @param height

   103      *            height in pixels

   104      *

   105      * @throws IllegalArgumentException

   106      *             if the width or height is less than one pixel

   107      */

   108     public CanvasGraphicsItem(int width, int height)

   109     {

   110         // Validate width and height.

   111         if (!(width >= 1 && height >= 1))

   112         {

   113             throw new IllegalArgumentException(ERROR_GIVEN_ARGUMENTS_NOT_VALID);

   114         }

   115 

   116         // Toolkit invoker is needed for accessing javax.microedition.lcdui

   117         // package

   118         iToolkitInvoker = ToolkitInvoker.getToolkitInvoker();

   119         iToolkit = iToolkitInvoker.getToolkit();

   120 

   121         // Create painter

   122         iItemPainter =

   123             CanvasGraphicsItemPainterInvoker.createCanvasGraphicsItemPainter(

   124                 this, iToolkit, width, height);

   125 

   126         int painterHandle = iItemPainter.getHandle();

   127 

   128         int handle = 0;

   129 

   130         synchronized (iToolkit)

   131         {

   132             // Create native peer object for this Java object.

   133             handle =

   134                 _createNativePeer(getToolkitHandle(), painterHandle, width,

   135                                   height);

   136         }

   137 

   138         // Check if construction failed and throw out of memory error.

   139         if (handle <= NativeError.KErrNone)

   140         {

   141             throw new OutOfMemoryError();

   142         }

   143 

   144         // Operation was a success, store size.

   145         iWidth = width;

   146         iHeight = height;

   147 

   148         // Sets parent to null

   149         iParent = null;

   150 

   151         // Set visibility

   152         iVisible = false;

   153 

   154         // Construction was successful. Store handle and register for

   155         // finalization.

   156         iHandle = handle;

   157 

   158         mFinalizer = new Finalizer()

   159         {

   160             public void finalizeImpl()

   161             {

   162                 registeredFinalize();

   163             }

   164         };

   165     }

   166 

   167     /**

   168      * Set the parent object of this <code>CanvasGraphicsItem</code>.

   169      *

   170      * Typically the parent object would be Canvas. Setting the parameter to

   171      * null removes the association to the parent. If

   172      * <code>setParent(null)</code> is called for a

   173      * <code>CanvasGraphicsItem</code> yet not having any parent or

   174      * <code>setParent(parent)</code> is called with the same parent, the call

   175      * is silently ignored.

   176      *

   177      * @param parent

   178      *            the parent object

   179      *

   180      * @throws IllegalArgumentException

   181      *             if <code>aParent</code> is not a valid object with which a

   182      *             CanvasGraphicsItem can be associated, or if CanvasItem

   183      *             is already set to another another parent

   184      */

   185     public void setParent(java.lang.Object parent)

   186     {

   187         // Ignore argument check if parent is set to null.

   188         // Custom item support will be added in future, currently it's

   189         // unsupported.

   190         if (((parent != null) && !(parent instanceof Canvas)) ||

   191                 ((parent != null) && (iParent != null) && (iParent != parent)))

   192         {

   193             throw new IllegalArgumentException(ERROR_NOT_A_VALID_PARENT_OBJECT);

   194         }

   195 

   196         if (parent != iParent)

   197         {

   198             // Lock this object so that parent cannot be adjusted from other

   199             // threads.

   200             synchronized (iToolkit)

   201             {

   202                 int parentHandle = 0;

   203 

   204                 // Toolkit invoker can be used to get proper handles.

   205                 if (parent instanceof Canvas)

   206                 {

   207                     // Note that canvas is shown inside a displayable so in this

   208                     // case we use the handle to the displayble object.

   209                     parentHandle = iToolkitInvoker.getDisplayableHandle(parent);

   210                 }

   211                 else if (parent instanceof CustomItem)

   212                 {

   213                     parentHandle = iToolkitInvoker.itemGetHandle(parent);

   214                 }

   215 

   216                 // parentHandle = 0 indicates removal of the parent.

   217                 int error =

   218                     _setParent(getToolkitHandle(), iHandle, parentHandle);

   219 

   220                 // Check if an error occured when setting the parent object.

   221                 NativeError.check(error);

   222 

   223                 // Store new parent

   224                 iParent = parent;

   225             }

   226         }

   227     }

   228 

   229     /**

   230      * Sets the size of this <code>CanvasGraphicsItem</code> in pixels.

   231      *

   232      * @param width

   233      *            width in pixels

   234      * @param height

   235      *            height in pixels

   236      *

   237      * @throws IllegalArgumentException

   238      *             if the width or height is less than one pixel

   239      */

   240     public void setSize(int width, int height)

   241     {

   242         // Validate width and row count

   243         if (width < 1 || height < 1)

   244         {

   245             throw new IllegalArgumentException(ERROR_GIVEN_ARGUMENTS_NOT_VALID);

   246         }

   247 

   248         synchronized (iToolkit)

   249         {

   250             NativeError.check(_setSize(getToolkitHandle(), iHandle, width,

   251                                        height));

   252 

   253             // Operation was a success, store size.

   254             iWidth = width;

   255             iHeight = height;

   256         }

   257     }

   258 

   259     /**

   260      * <P>

   261      * Sets the rendering position of this <code>CanvasGraphicsItem</code>. The

   262      * anchor point given is relative to the upper left corner of the target

   263      * <code>Canvas</code>.

   264      * </P>

   265      *

   266      * <P>

   267      * The <code>CanvasGraphicsItem</code> may be placed fully off or partially

   268      * of the visible area of the target <code>Canvas</code> by the

   269      * <code>setPosition</code> method; in this case the

   270      * <code>CanvasGraphicsItem</code> is just parly visible.

   271      * </P>

   272      *

   273      * @param x

   274      *            the x coordinate of the anchor point, in pixels.

   275      * @param y

   276      *            the y coordinate of the anchor point, in pixels.

   277      *

   278      * @throws IllegalStateException

   279      *             if a valid parent object hasn't been set.

   280      *

   281      * @see #setParent(java.lang.Object aParent)

   282      */

   283     public void setPosition(int x, int y)

   284     {

   285         synchronized (iToolkit)

   286         {

   287             checkParent();

   288 

   289             NativeError.check(_setPosition(getToolkitHandle(), iHandle, x, y));

   290 

   291             // Store current position.

   292             iPositionX = x;

   293             iPositionY = y;

   294         }

   295     }

   296 

   297     /**

   298      * <P>

   299      * Sets the visibility value of <code>CanvasGraphicsItem</code>. Initially

   300      * <code>CanvasGraphicsItem</code> is not visible so it must be explicitly

   301      * set to visible in order it to appear on UI.

   302      * </P>

   303      *

   304      * <P>

   305      * Setting visibility to true shows the graphics item with its content. If

   306      * the graphics item is already visible calling

   307      * <code>setVisible(true)</code> does nothing.

   308      * </P>

   309      *

   310      * <P>

   311      * Setting the visibility to false hides the graphics item and its content.

   312      * If the graphics item is already hidden calling

   313      * <code>setVisible(false)</code> does nothing.

   314      * </P>

   315      *

   316      * @param visible

   317      *            visibility of the <code>CanvasGraphicsItem</code>

   318      *

   319      * @throws IllegalStateException

   320      *             if a valid parent object has not been set.

   321      *

   322      * @see #setParent(java.lang.Object aParent)

   323      */

   324     public void setVisible(boolean visible)

   325     {

   326         synchronized (iToolkit)

   327         {

   328             checkParent();

   329 

   330             NativeError

   331             .check(_setVisible(getToolkitHandle(), iHandle, visible));

   332 

   333             iVisible = visible;

   334         }

   335     }

   336 

   337     /**

   338      * <P>

   339      * Sets the Z-position (elevation) of the item.

   340      * <p>

   341      * The Z-position decides the stacking order of items on the same parent. An

   342      * item of higher Z-position will be drawn on top of an item with a lower

   343      * Z-position.

   344      * <p>

   345      * The Z-position is unique for each item, meaning that changing a

   346      * Z-position of an item may change the Z-position of the items that share

   347      * the same parent. The Z-position does not affect the item's size in any

   348      * way.

   349      * <p>

   350      * When items are added with {@link CanvasItem#setParent} they will get a

   351      * Z-position that is increased by 1 from the item that is the top most item

   352      * at that time.

   353      * </P>

   354      *

   355      * @param z

   356      *            the Z-position of the item.

   357      *

   358      * @throws IllegalArgumentException

   359      *             if <code>z</code> < 0

   360      * @throws IllegalStateException

   361      *             if a valid parent object has not been set.

   362      *

   363      * @see #getZPosition()

   364      * @see #setParent(java.lang.Object aParent)

   365      */

   366     public void setZPosition(int z)

   367     {

   368         if (z < 0)

   369         {

   370             throw new IllegalArgumentException();

   371         }

   372 

   373         synchronized (iToolkit)

   374         {

   375             checkParent();

   376 

   377             NativeError.check(_setZPosition(getToolkitHandle(), iHandle, z));

   378         }

   379     }

   380 

   381     /**

   382      * <P>

   383      * Returns the Z-position (elevation) of the item.

   384      *

   385      * @see #setZPosition(int) </P>

   386      *

   387      * @throws IllegalStateException

   388      *             if a valid parent object has not been set.

   389      *

   390      * @see #setParent(java.lang.Object aParent)

   391      */

   392     public int getZPosition()

   393     {

   394         int positionZ = -1;

   395 

   396         synchronized (iToolkit)

   397         {

   398             checkParent();

   399 

   400             positionZ = _getZPosition(getToolkitHandle(), iHandle);

   401         }

   402 

   403         NativeError.check(positionZ);

   404 

   405         return positionZ;

   406     }

   407 

   408     /*

   409      * Hidden default constructor.

   410      */

   411     CanvasGraphicsItem()

   412     {

   413     }

   414 

   415     /**

   416      * <P>

   417      * Renders the <code>CanvasGraphicsItem</code>.

   418      * <P>

   419      * The application implements this method to paint graphics on

   420      * <code>CanvasGraphicsItem</code>.

   421      * <P>

   422      * <code>CanvasGraphicsItem</code> paint works in the same way as

   423      * <code>Canvas</code> paint method. The only difference to

   424      * <code>Canvas</code> paint method is that application does not need to

   425      * paint all the pixels of the clip region as that the clip region needing

   426      * updating is cleared and fully transparent before paint is called. Content

   427      * rendered by application in previous paint method calls is not available

   428      * in the clip region. Coordinates used in <code>Graphics</code> methods are

   429      * relative to <code>CanvasGraphicsItem</code> itself. This means (0,0)

   430      * coordinate is top left pixel of <code>CanvasGraphicsItem</code> as

   431      * positioned in the containing parent (e.g. <code>Canvas</code>).

   432      * </P>

   433      *

   434      * @param graphics

   435      *            the <code>Graphics</code> object to be used for rendering the

   436      *            <code>Canvas</code>

   437      *

   438      */

   439     protected abstract void paint(javax.microedition.lcdui.Graphics graphics);

   440 

   441     /**

   442      * Requests a repaint for the specified region of the

   443      * <code>CanvasGraphicsItem</code>.

   444      * <P>

   445      * Coordinates are relative to the <code>CanvasGraphicsItem</code>

   446      * coordinates. The method works in similar manner as <code>Canvas</code>

   447      * repaint method.

   448      *

   449      * @param x

   450      *            the x coordinate of the rectangle to be repainted, in pixels

   451      * @param y

   452      *            the y coordinate of the rectangle to be repainted, in pixels

   453      * @param width

   454      *            the width of the rectangle to be repainted, in pixels

   455      * @param height

   456      *            the height of the rectangle to be repainted, in pixels

   457      *

   458      */

   459     public final void repaint(int x, int y, int width, int height)

   460     {

   461         iItemPainter.Repaint(x, y, width, height);

   462     }

   463 

   464     /**

   465      * Requests a repaint for the entire <code>CanvasGraphicsItem</code>. The

   466      * effect is identical to

   467      * <code>repaint(0, 0, getWidth(), getHeight());</code>

   468      *

   469      * @see #repaint(int x, int y, int width, int height)

   470      */

   471     public final void repaint()

   472     {

   473         iItemPainter.Repaint(0, 0, getWidth(), getHeight());

   474     }

   475 

   476     /*

   477      * Disposes the Landmark native peer object, if the handles are valid.

   478      * Invalid (negative) handles indicate that their creation failed in the

   479      * first place.

   480      */

   481     final void registeredFinalize()

   482     {

   483         if (mFinalizer != null )

   484         {

   485             synchronized (iToolkit)

   486             {

   487                 if (iHandle != 0)

   488                 {

   489                     iToolkitInvoker.toolkitDisposeObject(iToolkit,iHandle);

   490                     iHandle = 0;

   491                 }

   492             }

   493             mFinalizer = null;

   494         }

   495     }

   496 

   497     void Repaint(Graphics aGraphics)

   498     {

   499         paint(aGraphics);

   500     }

   501 

   502     /*

   503      * Returns the native side handle to the LCDUI Toolkit.

   504      *

   505      * @return The native side handle to the LCDUI Toolkit.

   506      */

   507     synchronized int getToolkitHandle()

   508     {

   509         return iToolkitInvoker.toolkitGetHandle(iToolkit);

   510     }

   511 

   512     // Native methods

   513 

   514     /*

   515      * Creates the native side peer object for this CanvasGraphicsItem.

   516      *

   517      * @param aToolkitHandle A handle to the LCDUI toolkit.

   518      *

   519      * @param aPainterHandle A handle of a CanvasGraphicsItemPainter native side

   520      * peer

   521      *

   522      * @param width The new width of this canvas graphics item.

   523      *

   524      * @param height The new hight of this canvas graphics item.

   525      *

   526      * @return A handle to the the native side peer object or a system-wide

   527      * error code.

   528      */

   529     private native int _createNativePeer(

   530         int aToolkitHandle,

   531         int aPainterHandle,

   532         int width,

   533         int height);

   534 

   535     /*

   536      * Disposes the native side peer object.

   537      *

   538      * @param aToolkitHandle A handle to the LCDUI toolkit.

   539      *

   540      * @param aNativePeerHandle A handle to the native side peer object.

   541      */

   542     private native void _dispose(int aToolkitHandle, int aNativePeerHandle);

   543 

   544     /*

   545      * Sets the size of this graphics item using the given width and height.

   546      *

   547      * @param aToolkitHandle A handle to the LCDUI toolkit.

   548      *

   549      * @param aNativePeerHandle A handle to the native side peer object.

   550      *

   551      * @param width The new width of this graphics item.

   552      *

   553      * @param height The new hight of this graphics item.

   554      *

   555      * @return NativeError.KErrNone if the operation was successful. Otherwise,

   556      * a system-wide error code is returned.

   557      */

   558     private native int _setSize(

   559         int aToolkitHandle,

   560         int aNativePeerHandle,

   561         int width,

   562         int height);

   563 

   564     /*

   565      * Disposes the native side peer object.

   566      *

   567      * @param aToolkitHandle A handle to the LCDUI toolkit.

   568      *

   569      * @param aNativePeerHandle A handle to the native side peer object.

   570      *

   571      * @param aParentHandle A handle to the parent object.

   572      *

   573      * @return NativeError.KErrNone if the operation was successful. Otherwise,

   574      * a system-wide error code is returned.

   575      */

   576     private native int _setParent(

   577         int aToolkitHandle,

   578         int aNativePeerHandle,

   579         int aParentHandle);

   580 

   581     /*

   582      * Sets the graphics item visible.

   583      *

   584      * @param aToolkitHandle A handle to the LCDUI toolkit.

   585      *

   586      * @param aNativePeerHandle A handle to the native side peer object.

   587      *

   588      * @param aVisible The visibility status of this graphics item.

   589      *

   590      * @return NativeError.KErrNone if the operation was successful. Otherwise,

   591      * a system-wide error code is returned.

   592      */

   593     private native int _setVisible(

   594         int aToolkitHandle,

   595         int aNativePeerHandle,

   596         boolean aVisible);

   597 

   598     /*

   599      * Sets the graphics item's position.

   600      *

   601      * @param aToolkitHandle A handle to the LCDUI toolkit.

   602      *

   603      * @param aNativePeerHandle A handle to the native side peer object.

   604      *

   605      * @param x The x coordinate of the anchor point.

   606      *

   607      * @param y The y coordinate of the anchor point.

   608      *

   609      * @return NativeError.KErrNone if the operation was successful. Otherwise,

   610      * a system-wide error code is returned.

   611      */

   612     private native int _setPosition(

   613         int aToolkitHandle,

   614         int aNativePeerHandle,

   615         int x,

   616         int y);

   617 

   618     /*

   619      * Sets the elevation of this graphics item.

   620      *

   621      * @param aToolkitHandle A handle to the LCDUI toolkit.

   622      *

   623      * @param aNativePeerHandle A handle to the native side peer object.

   624      *

   625      * @param aZ The new z-position.

   626      *

   627      * @return NativeError.KErrNone if the operation was successful. Otherwise,

   628      * a system-wide error code is returned.

   629      */

   630     private native int _setZPosition(

   631         int aToolkitHandle,

   632         int aNativePeerHandle,

   633         int aZ);

   634 

   635     /*

   636      * Gets the elevation of this graphics item.

   637      *

   638      * @param aToolkitHandle A handle to the LCDUI toolkit.

   639      *

   640      * @param aNativePeerHandle A handle to the native side peer object.

   641      *

   642      * @return The elevation if the operation was successful. Otherwise, a

   643      * system-wide error code is returned.

   644      */

   645     private native int _getZPosition(int aToolkitHandle, int aNativePeerHandle);

   646 }