1 /* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     2  * All rights reserved.

     3  * This component and the accompanying materials are made available

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

     5  * which accompanies this distribution, and is available

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

     7  *

     8  * Initial Contributors:

     9  * Nokia Corporation - initial contribution.

    10  *

    11  * Contributors:

    12  *

    13  * Description: Package private class implementing the S40 and S60 interfaces

    14  * for TextEditor

    15  *

    16  */

    17 

    18 // PACKAGE

    19 package com.nokia.mid.ui;

    20 

    21 // INTERNAL IMPORTS

    22 import com.nokia.mid.ui.impl.LCDUIPackageInvoker;

    23 import com.nokia.mid.ui.impl.TextEditorListenerImpl;

    24 import com.nokia.mid.ui.impl.TextEditorContainer;

    25 

    26 // EXTERNAL IMPORTS

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

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

    29 import javax.microedition.lcdui.Canvas;

    30 

    31 /*

    32  *

    33  *

    34  * @since 1.4

    35  */

    36 class TextEditorImpl

    37         extends com.nokia.mid.ui.TextEditor

    38         implements com.nokia.mid.ui.S60TextEditor

    39 {

    40     /*

    41      * Indicates that all input methods are available.

    42      * <p>

    43      * Can be used in {@link #setDisabledTouchInputModes}.

    44      */

    45     public static final int TOUCH_INPUT_ALL_AVAILABLE   = 0;

    46 

    47     /*

    48      *  Handwriting recognition

    49      */

    50     public static final int TOUCH_INPUT_HWR             = 1;

    51 

    52     /*

    53      *  Virtual QWERTY keyboard

    54      */

    55     public static final int TOUCH_INPUT_VKB             = 2;

    56 

    57     /*

    58      *  Full screen QWERTY keyboard

    59      */

    60     public static final int TOUCH_INPUT_FSQ             = 4;

    61 

    62     /*

    63      *  Alphanumeric keyboard with ITU-T input

    64      */

    65     public static final int TOUCH_INPUT_ITUT            = 8;

    66 

    67     /*

    68      *  Full screen handwriting recognition

    69      */

    70     public static final int TOUCH_INPUT_FSC             = 16;

    71 

    72     /*

    73      *  Mini ITU-T for Japanese devices

    74      */

    75     public static final int TOUCH_INPUT_MINI_ITUT       = 32;

    76 

    77     // Private static data.

    78     private static final int INDICATOR_SIZE_COUNT       = 2;

    79 

    80     // Mask of all bits defined

    81     private static final int MASK =

    82         TOUCH_INPUT_HWR | TOUCH_INPUT_VKB | TOUCH_INPUT_FSQ |

    83         TOUCH_INPUT_ITUT | TOUCH_INPUT_FSC | TOUCH_INPUT_MINI_ITUT;

    84 

    85     /*

    86      * <P>

    87      * Creates a new <code>TextEditor</code> object with the given initial contents,

    88      * maximum size in characters, constraints and editor size in pixels.

    89      * </P>

    90      *

    91      * <P>

    92      * If the text parameter is <code>null</code>, the <code>TextEditor</code> is

    93      * created empty.

    94      * </P>

    95      *

    96      * <P>

    97      * The <code>maxSize</code> parameter must be greater than zero. An

    98      * <code>IllegalArgumentException</code> is thrown if the length of the initial

    99      * contents string exceeds <code>maxSize</code>. However, the implementation

   100      * may assign a maximum size smaller than the application had requested. If

   101      * this occurs, and if the length of the contents exceeds the newly assigned

   102      * maximum size, the contents are truncated from the end in order to fit,

   103      * and no exception is thrown.

   104      * </P>

   105      *

   106      * @param aText

   107      *            the initial contents, or <code>null</code> if the

   108      *            <code>TextEditor</code> is to be created empty

   109      * @param aMaxSize

   110      *            the maximum capacity in characters

   111      * @param aConstraints

   112      *            see the input constraints in <code>TextField</code></a>

   113      * @param aWidth

   114      *            the width of the bounding box, in pixels

   115      * @param aHeight

   116      *            the height of the bounding box, in pixels

   117      *

   118      * @throws IllegalArgumentException

   119      *             if <code>aMaxSize</code> is zero or less

   120      * @throws IllegalArgumentException

   121      *             if the value of the constraints parameter is invalid

   122      * @throws IllegalArgumentException

   123      *             if <code>aText</code> is illegal for the specified

   124      *             constraints

   125      * @throws IllegalArgumentException

   126      *             if the length of the string exceeds the requested maximum

   127      *             capacity

   128      * @throws IllegalArgumentException

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

   130      */

   131     TextEditorImpl(String aText, int aMaxSize, int aConstraints, int aWidth,

   132                    int aHeight)

   133     {

   134         super(aText, aMaxSize, aConstraints, aWidth, aHeight, false);

   135     }

   136 

   137     /*

   138      * <P>

   139      * Creates a new empty <code>TextEditor</code> with the given maximum size in

   140      * characters, constraints and editor size as number of visible rows.

   141      * </P>

   142      *

   143      * <P>

   144      * The <code>rows</code> parameter indicates the requested number of visible

   145      * rows in the editor. TextEditor then assigns the initial

   146      * height for the editor based on the requested number of rows and width of the

   147      * editor.

   148      * </P>

   149      *

   150      * <P>

   151      * The <code>maxSize</code> parameter must be greater than zero. An

   152      * <code>IllegalArgumentException</code> is thrown if the length of the initial

   153      * contents string exceeds <code>maxSize</code>. However, the implementation

   154      * may assign a maximum size smaller than the application had requested. If

   155      * this occurs, and if the length of the contents exceeds the newly assigned

   156      * maximum size, the contents are truncated from the end in order to fit,

   157      * and no exception is thrown.

   158      * </P>

   159      *

   160      * @param aMaxSize

   161      *            the maximum capacity in characters

   162      * @param aConstraints

   163      *            see the input constraints in <code>TextField</code></a>

   164      * @param aWidth

   165      *            the width of the bounding box, in pixels

   166      * @param aRows

   167      *            the requested number of visible rows in the editor

   168      *

   169      * @throws IllegalArgumentException

   170      *             if <code>aMaxSize</code> or <code>rows</code> is zero or less

   171      * @throws IllegalArgumentException

   172      *             if the value of the constraints parameter is invalid

   173      * @throws IllegalArgumentException

   174      *             if the width is less than one pixel

   175      */

   176     TextEditorImpl(int aMaxSize, int aConstraints, int aWidth, int aRows)

   177     {

   178         super(null, aMaxSize, aConstraints, aWidth, aRows, true);

   179     }

   180 

   181     /*

   182      * Set the parent object of this TextEditor. Typically in LCDUI the parent

   183      * object would be Canvas or CustomItem. Setting the parameter to null

   184      * removes the association to the parent.

   185      * <p>

   186      * @param aParent the parent object

   187      * <p>

   188      * @throws IllegalArgumentException

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

   190      *              TextEditor can be associated

   191      */

   192     public void setParent(Object aParent)

   193     {

   194         super.setParent(aParent);

   195         // Update indicator location to their default position.

   196         if (aParent != null)

   197         {

   198             setDefaultIndicators();

   199         }

   200     }

   201 

   202     /*

   203      * <P>

   204      * If the default indicator location is not used then sets the drawing

   205      * location for input indicators relative to the <code>TextEditor</code>'s

   206      * parent.

   207      * </P>

   208      *

   209      * <P>

   210      * The anchor point given is relative to the upper left corner of the

   211      * <code>Canvas</code>. The location may be outside the

   212      * <code>TextEditor</code> boundaries. The z-order of the indicators is the

   213      * same as <code>TextEditor</code> textual content. If indicators and the

   214      * editor content overlap indicators are rendered on top of the editor

   215      * content.

   216      * </P>

   217      *

   218      * <P>

   219      * The application should first query the size of the input indicators with

   220      * {@link #getIndicatorSize} method to determine that the indicators will

   221      * not be clipped outside the available display area when drawn to the

   222      * requested location.

   223      * </P>

   224      *

   225      * <P>

   226      * If there are no indicators present, the usability of complex device

   227      * specific input methods may be compromised.

   228      * </P>

   229      *

   230      * @param x

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

   232      * @param y

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

   234      *

   235      */

   236     public void setIndicatorLocation(int x, int y)

   237     {

   238         synchronized (iToolkit)

   239         {

   240             NativeError.check(_setIndicatorLocation(getToolkitHandle(),

   241                                                     iHandle, x, y));

   242         }

   243     }

   244 

   245     /*

   246      * <P>

   247      * Resets the implementation provided input indicators to their default

   248      * position.

   249      * </P>

   250      *

   251      * <P>

   252      * This position may be outside the area of parent in case the default

   253      * position is in status area. In this case if the status area is missing

   254      * (full screen mode Canvas) the default position is inside the parent area

   255      * e.g. on top of the editor. When default position is in use the

   256      * <code>TextEditor</code> automatically positions the indicators relative

   257      * to the <code>TextEditor</code> even when <code>TextEditor</code> location

   258      * is changed. However, client is responsible of making sure indicators are

   259      * visible inside the parent area positioning <code>TextEditor</code> so

   260      * that indicators fit to the visible area e.g. on top of the

   261      * <code>TextEditor</code>. Positioning <code>TextEditor</code> directly on

   262      * top of <code>Canvas</code> may mean that indicators in the default

   263      * position are not visible.

   264      * </P>

   265      *

   266      * @throws IllegalStateException

   267      *             If the <code>TextEditor</code> is not added to

   268      *             <code>Canvas</code>

   269      */

   270     public void setDefaultIndicators()

   271     {

   272         synchronized (iToolkit)

   273         {

   274             Object parent = getParent();

   275             boolean fullScreen = false;

   276 

   277             if (parent instanceof Canvas)

   278             {

   279                 fullScreen = iLCDUIPackageInvoker.isFullScreen((Canvas) parent);

   280             }

   281 

   282             NativeError.check(_setDefaultIndicators(getToolkitHandle(),

   283                                                     iHandle, fullScreen));

   284         }

   285     }

   286 

   287     /*

   288      * <P>

   289      * By default indicators visibility is set to <code>true</code> and they are

   290      * made visible when the associated <code>TextEditor</code> is focused.

   291      * </P>

   292      * <P>

   293      * If the application controls the position of the indicators, those can be

   294      * explicitly made not visible by calling

   295      * <code>setIndicatorVisibility(false)</code>. Indicators are never visible

   296      * if <code>TextEditor</code> itself is not visible so having indicator

   297      * visibility set to <code>true</code> does not make them visible unless

   298      * editor itself is set visible.

   299      * </P>

   300      *

   301      * @param visible

   302      *            controls indicator visibility state

   303      *

   304      * @see #setIndicatorLocation(int, int)

   305      * @see #setDefaultIndicators()

   306      */

   307     public void setIndicatorVisibility(boolean visible)

   308     {

   309         synchronized (iToolkit)

   310         {

   311             NativeError.check(_setIndicatorVisibility(getToolkitHandle(),

   312                               iHandle, visible));

   313         }

   314     }

   315 

   316     /*

   317      * Gets the size of the area needed for drawing the input indicators.

   318      * <p>

   319      * The returned array contains two integers for width (array index 0) and

   320      * height (array index 1) of the indicator graphics. Size (0,0) is returned

   321      * if the device UI does not use any input indicators in the text editors or

   322      * if the indicators are curretly positioned outside parent area e.g. in

   323      * status area. This happens if {@link #setIndicatorLocation(int, int)

   324      * setIndicatorLocation(int x, int y)} has not been ever called for the

   325      * editor, or if {@link #setDefaultIndicators() setDefaultIndicators()} has

   326      * been called.

   327      * <p>

   328      *

   329      * @return the width and height of area needed for drawing input indicators

   330      * @see #setDefaultIndicators()

   331      */

   332     public int[] getIndicatorSize()

   333     {

   334         int[] size = new int[INDICATOR_SIZE_COUNT];

   335 

   336         synchronized (iToolkit)

   337         {

   338             NativeError.check(_getIndicatorSize(getToolkitHandle(), iHandle,

   339                                                 size));

   340         }

   341         return size;

   342     }

   343 

   344     /*

   345      * Disables one or multiple touch input modes from use.

   346      * <p>

   347      * User is not able to switch to the disable touch input modes. Multiple

   348      * touch input modes may be combined together in <code>touchInputMode</code>

   349      * parameter using bitwise or operator. The method does not have any impact

   350      * if called in non-touch device. A device may not support all touch input

   351      * modes specified. Specifying not supported input modes is silently

   352      * ignored.

   353      * <p>

   354      * The possible values are defined in the class with TOUCH_INPUT_* starting

   355      * constant values.

   356      * <p>

   357      *

   358      * @param touchInputModes

   359      *            bitwise or combined list of disabled touch input modes

   360      * @throws IllegalArgumentException

   361      *             if the given input modes are not valid.

   362      *             <p>

   363      * @see #setPreferredTouchMode(int)

   364      * @see #getDisabledTouchInputModes()

   365      */

   366     public void setDisabledTouchInputModes(int touchInputModes)

   367     {

   368         // Validate touch input modes. There must not be additional modes

   369         // 0 is valid.

   370         // See com.nokia.mid.ui.s60.TextEditor.TOUCH_INPUT_ALL_AVAILABLE.

   371         if ((touchInputModes & ~MASK) != 0)

   372         {

   373             throw new IllegalArgumentException();

   374         }

   375 

   376         synchronized (iToolkit)

   377         {

   378             NativeError.check(_setDisabledTouchInputModes(getToolkitHandle(),

   379                               iHandle, touchInputModes));

   380         }

   381     }

   382 

   383     /*

   384      * By default all supported touch input modes are available. Returns the

   385      * disabled touch input modes set with {@link #setDisabledTouchInputModes}.

   386      * <p>

   387      * Note that the disabled touch input modes may be device specific so this

   388      * method may return some modes as disabled by default.

   389      * <p>

   390      * Note that if the device does not support touch input this method returns

   391      * all modes.

   392      * <p>

   393      *

   394      * @return The disabled touch input modes.

   395      * @see #setDisabledTouchInputModes(int)

   396      * @see #setPreferredTouchMode(int)

   397      */

   398     public int getDisabledTouchInputModes()

   399     {

   400         int disabled = 0;

   401 

   402         synchronized (iToolkit)

   403         {

   404             disabled = _getDisabledTouchInputModes(getToolkitHandle(), iHandle);

   405         }

   406 

   407         NativeError.check(disabled);

   408         return disabled;

   409     }

   410 

   411     /*

   412      * Set the preferred touch input mode overriding the device default

   413      * preferred mode. User may still change the touch input mode from touch

   414      * input window to all available modes.

   415      * <p>

   416      * The possible values are defined in the class with TOUCH_INPUT_* starting

   417      * constant values.

   418      * <p>

   419      * Note that if the device does not support touch input this method has no

   420      * effect.

   421      * <p>

   422      *

   423      * @param touchInputModes

   424      *            a touch input mode to be set as preferred one.

   425      * @throws IllegalArgumentException

   426      *             if the input mode is not valid or if it contains multiple

   427      *             input modes as bit mask.

   428      * @see #setDisabledTouchInputModes(int)

   429      * @see #getPreferredTouchMode()

   430      *

   431      */

   432     public void setPreferredTouchMode(int touchInputModes)

   433     {

   434         int mask = touchInputModes & MASK;

   435         // Validate touch input mode.

   436         if (touchInputModes == 0 || (touchInputModes & ~MASK) != 0

   437                 || (mask & (mask - 1)) != 0)

   438         {

   439             throw new IllegalArgumentException();

   440         }

   441 

   442         synchronized (iToolkit)

   443         {

   444             NativeError.check(_setPreferredTouchMode(getToolkitHandle(),

   445                               iHandle, touchInputModes));

   446         }

   447     }

   448 

   449     /*

   450      * Gets the preferred touch input mode.

   451      * <p>

   452      * Note that if the device does not support touch input this method returns

   453      * <code>0</code>

   454      * <p>

   455      *

   456      * @return The preferred touch input mode.

   457      *         <p>

   458      * @see #setPreferredTouchMode(int)

   459      * @see #setDisabledTouchInputModes(int)

   460      */

   461     public int getPreferredTouchMode()

   462     {

   463         int preferredMode = 0;

   464 

   465         synchronized (iToolkit)

   466         {

   467             preferredMode = _getPreferredTouchMode(getToolkitHandle(), iHandle);

   468         }

   469 

   470         NativeError.check(preferredMode);

   471         return preferredMode;

   472     }

   473 

   474     /*

   475      * Sets the caret in the Editor at x, y location.

   476      *

   477      * @param x

   478      *      The x coordinate of the wanted caret position.

   479      *

   480      * @param y

   481      *      The y coordinate of the wanted caret position.

   482      */

   483     public void setCaretXY(int x, int y)

   484     {

   485         synchronized (iToolkit)

   486         {

   487             NativeError.check(_setCaretXY(getToolkitHandle(), iHandle, x, y));

   488         }

   489     }

   490 

   491     /*

   492      * Hidden default constructor.

   493      */

   494     private TextEditorImpl()

   495     {

   496     }

   497 

   498     // Private methods.

   499 

   500     /*

   501      * Sets the visibility status of the indicator of the editor.

   502      *

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

   504      *

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

   506      *

   507      * @param aVisible The visibility status of the indicator.

   508      *

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

   510      * a system-wide error code is returned.

   511      */

   512     private native int _setIndicatorVisibility(

   513         int aToolkitHandle,

   514         int aNativePeerHandle,

   515         boolean aVisible);

   516 

   517     /*

   518      * Sets the position of the indicator.

   519      *

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

   521      *

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

   523      *

   524      * @param aX The x coordinate of the anchor point.

   525      *

   526      * @param aY The y coordinate of the anchor point.

   527      *

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

   529      * a system-wide error code is returned.

   530      */

   531     private native int _setIndicatorLocation(

   532         int aToolkitHandle,

   533         int aNativePeerHandle,

   534         int aX,

   535         int aY);

   536 

   537     /*

   538      * Gets the size of the area needed for drawing the input indicators.

   539      *

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

   541      *

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

   543      *

   544      * @param aSize On return, contains the size of the indicator (w,h).

   545      *

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

   547      * a system-wide error code is returned.

   548      */

   549     private native int _getIndicatorSize(

   550         int aToolkitHandle,

   551         int aNativePeerHandle,

   552         int[] aSize);

   553 

   554     /*

   555      * Resets the default input indicators to be used.

   556      *

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

   558      *

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

   560      *

   561      * @param aParentFullScreen Indicates if parent is the size of the whole

   562      * screen.

   563      *

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

   565      * a system-wide error code is returned.

   566      */

   567     private native int _setDefaultIndicators(

   568         int aToolkitHandle,

   569         int aNativePeerHandle,

   570         boolean aParentFullScreen);

   571 

   572     /*

   573      * Sets the disabled touch input modes.

   574      *

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

   576      *

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

   578      *

   579      * @param aTouchInputModes The disabled touch input modes.

   580      *

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

   582      * a system-wide error code is returned.

   583      */

   584     private native int _setDisabledTouchInputModes(

   585         int aToolkitHandle,

   586         int aNativePeerHandle,

   587         int aTouchInputModes);

   588 

   589     /*

   590      * Gets the disabled touch input mode.

   591      *

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

   593      *

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

   595      *

   596      * @param aTouchInputMode The preferred touch input mode.

   597      *

   598      * @return The disabled touch input modes if the operation was successful.

   599      * Otherwise, a system-wide error code is returned.

   600      */

   601     private native int _getDisabledTouchInputModes(

   602         int aToolkitHandle,

   603         int aNativePeerHandle);

   604 

   605     /*

   606      * Sets the preferred touch input mode.

   607      *

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

   609      *

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

   611      *

   612      * @param aTouchInputMode The preferred touch input mode.

   613      *

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

   615      * a system-wide error code is returned.

   616      */

   617     private native int _setPreferredTouchMode(

   618         int aToolkitHandle,

   619         int aNativePeerHandle,

   620         int aTouchInputMode);

   621 

   622     /*

   623      * Gets the preferred touch input mode.

   624      *

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

   626      *

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

   628      *

   629      * @return The preferred touch input mode if the operation was successful.

   630      * Otherwise, a system-wide error code is returned.

   631      */

   632     private native int _getPreferredTouchMode(

   633         int aToolkitHandle,

   634         int aNativePeerHandle);

   635 

   636     /*

   637      * Sets the caret in the Editor at x, y location.

   638      *

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

   640      *

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

   642      *

   643      * @param x

   644      *      The x coordinate of the wanted caret position.

   645      *

   646      * @param y

   647      *      The y coordinate of the wanted caret position.

   648      */

   649     public native int _setCaretXY(

   650         int aToolkitHandle,

   651         int aNativePeerHandle,

   652         int x,

   653         int y);

   654 }

   655 

   656 // End of file