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 class defining the interface for MIDP Text Editor

    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 com.nokia.mid.ui.CanvasItem;

    30 import javax.microedition.lcdui.Font;

    31 import javax.microedition.lcdui.Canvas;

    32 import javax.microedition.lcdui.CustomItem;

    33 import javax.microedition.lcdui.TextField;

    34 import java.util.Enumeration;

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

    36 

    37 /**

    38  * <P>

    39  * A <code>TextEditor</code> is an editable text component that is used with a

    40  * parent object; with <code>Canvas</code> or <code>CustomItem</code>. The

    41  * <code>TextEditor</code> maybe set to and removed from <code>Canvas</code>

    42  * through <code>setParent()</code> method.

    43  * </P>

    44  *

    45  * <P>

    46  * The implementation presents the <code>TextEditor</code> with minimal

    47  * decoration; only the caret is shown at the requested text insertion position.

    48  * It is the responsibility of the application to draw any additional decoration

    49  * like focus highlight, border or scroll bar. The animation of the caret, e.g.

    50  * blinking, is handled by the TextEditor implementation.

    51  * </P>

    52  *

    53  * <P>

    54  * <code>TextEditor</code> supports <em>input constraints</em> identically to

    55  * <code>TextField</code>. See <a href="TextField.html#constraints">input

    56  * constraints</a> section in the <code>TextField</code> for the definition of

    57  * these constants. In addition <code>TextEditor</code> has the same concept of

    58  * <em>actual contents</em> and <em>displayed contents</em> as

    59  * <code>TextField</code>; these are described in the same <a

    60  * href="TextField.html#constraints">input constraints</a> section.

    61  * </P>

    62  *

    63  * <P>

    64  * <code>TextEditor</code> supports <em>input modes</em> identically to

    65  * <code>TextField</code>. See <a href="TextField.html#modes">input modes</a>

    66  * section in the <code>TextField</code> for the definition of these constants.

    67  * </P>

    68  *

    69  * <P>

    70  * The text may contain <A HREF="Form.html#linebreak">line breaks</A>. The

    71  * display of the text must break accordingly and the user must be able to enter

    72  * line break characters.

    73  * </P>

    74  *

    75  * <P>

    76  * The TextEditor provides necessary interaction for example for touch input

    77  * (handwriting recognition) on touch screen devices and selection of additional

    78  * characters. The input on touch devices requires additional windows of top of

    79  * the editor window which depending on the implementation may obscure the

    80  * parent completely.

    81  * </P>

    82  *

    83  * <P>

    84  * Application can add a TextEditorListener to the <code>TextEditor</code> for

    85  * example for keeping track of user navigation (caret movement) and other

    86  * content changes such as text selection. The events are sent on all occasions

    87  * that cause the the caret position to change (including but not limited to

    88  * text typing by user, programmatic text insertion, navigation within the

    89  * <code>TextEditor</code> content, and text deletion). The events must be sent

    90  * to the application prior to they have effect on the editor - for example an

    91  * event indicating caret movement must be available for the application before

    92  * the implementation actually moves the caret in the editor.

    93  * </P>

    94  *

    95  * <P>

    96  * When the <code>TextEditor</code> has focus all the key events that are not

    97  * consumed by <code>TextEditor</code> with the current constraints or mapped to

    98  * Commands by the implementation are sent to <code>Canvas</code>.

    99  * </P>

   100  *

   101  * <P>

   102  * Touch pointer events are not delivered to parent object from the area of the

   103  * visible TextEditor.

   104  * </P>

   105  *

   106  * <P>

   107  * The implementation will scroll the <code>TextEditor</code> content

   108  * automatically on user interaction and when the application calls setCaret or

   109  * setSelection methods. For example if a user clicks down on the last visible

   110  * row the <code>TextEditor</code> content is scrolled accordingly by one row.

   111  * However the Java platform implementation does not draw any scroll bars, this

   112  * is left to the application.

   113  * </P>

   114  *

   115  * @since 1.4

   116  */

   117 

   118 public class TextEditor

   119         extends CanvasItem

   120 {

   121 

   122     // Protected data for extending classes.

   123 

   124     // LCDUI Toolkit object.

   125     Object iToolkit;

   126 

   127     // Native handle

   128     int iHandle;

   129 

   130     // LCDUI package invoker.

   131     LCDUIPackageInvoker iLCDUIPackageInvoker;

   132 

   133     // Change listener. May be NULL.

   134     TextEditorListenerImpl iListener;

   135 

   136     // Private data

   137 

   138     // LCDUI Toolkit invoker object.

   139     private ToolkitInvoker iToolkitInvoker;

   140     // The current set of constraints of this text editor component.

   141     private int iConstraints;

   142 

   143     // Initial input mode

   144     private java.lang.String iCharacterSubset;

   145 

   146     // The current maximum size of this text editor component.

   147     private int iMaxSize;

   148 

   149     // The current font of this text editor component

   150     private Font iFont;

   151 

   152     // Indicates receiving of pointer events by the editor

   153     private boolean iTouchEnabled;

   154 

   155     // Text editor container for handling editor focusing.

   156     private static TextEditorContainer iEditorContainer;

   157 

   158     // Color indicators. Must be in sync with MMIDTextEditor::TColorType

   159     private static final int COLOR_BACKGROUND = 0;

   160     private static final int COLOR_FOREGROUND = 1;

   161     private static final int COLOR_HIGHLIGHT_BACKGROUND = 2;

   162     private static final int COLOR_HIGHLIGHT_FOREGROUND = 3;

   163 

   164     // The maximum value for all colors.

   165     private static final int COLOR_MAX_VALUE = 255;

   166 

   167     // Static block for creating editor container.

   168     static

   169     {

   170         iEditorContainer = new TextEditorContainer();

   171     }

   172 

   173     private Finalizer mFinalizer;

   174 

   175     /**

   176      * <P>

   177      * Creates a new <code>TextEditor</code> object with the given initial

   178      * contents, maximum size in characters, constraints and editor size in

   179      * pixels.

   180      * </P>

   181      *

   182      * <P>

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

   184      * is created empty.

   185      * </P>

   186      *

   187      * <P>

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

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

   190      * initial contents string exceeds <code>maxSize</code>. However, the

   191      * implementation may assign a maximum size smaller than the application had

   192      * requested. If this occurs, and if the length of the contents exceeds the

   193      * newly assigned maximum size, the contents are truncated from the end in

   194      * order to fit, and no exception is thrown.

   195      * </P>

   196      *

   197      * <P>

   198      * On Series60-devices, if the MIDlet is manufacturer or operator-signed,

   199      * the object returned by this method will also implement the

   200      * com.nokia.mid.ui.s60.TextEditor

   201      * </P>

   202      *

   203      * @param text

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

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

   206      * @param maxSize

   207      *            the maximum capacity in characters

   208      * @param constraints

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

   210      * @param width

   211      *            the width of the bounding box, in pixels

   212      * @param height

   213      *            the height of the bounding box, in pixels

   214      * @return Instance of TextEditor

   215      *

   216      * @throws IllegalArgumentException

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

   218      * @throws IllegalArgumentException

   219      *             if the value of the constraints parameter is invalid

   220      * @throws IllegalArgumentException

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

   222      *             constraints

   223      * @throws IllegalArgumentException

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

   225      *             capacity

   226      * @throws IllegalArgumentException

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

   228      */

   229     public static TextEditor createTextEditor(

   230         String text,

   231         int maxSize,

   232         int constraints,

   233         int width,

   234         int height)

   235     {

   236         return new TextEditorImpl(text, maxSize, constraints, width, height);

   237     }

   238 

   239     /**

   240      * <P>

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

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

   243      * </P>

   244      *

   245      * <P>

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

   247      * rows in the editor. TextEditor then assigns the initial height for the

   248      * editor based on the requested number of rows and width of the editor.

   249      * </P>

   250      *

   251      * <P>

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

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

   254      * initial contents string exceeds <code>maxSize</code>. However, the

   255      * implementation may assign a maximum size smaller than the application had

   256      * requested. If this occurs, and if the length of the contents exceeds the

   257      * newly assigned maximum size, the contents are truncated from the end in

   258      * order to fit, and no exception is thrown.

   259      * </P>

   260      *

   261      * <P>

   262      * On Series60-devices, if the MIDlet is manufacturer or operator-signed,

   263      * the object returned by this method will also implement the

   264      * com.nokia.mid.ui.s60.TextEditor

   265      * </P>

   266      *

   267      * @param maxSize

   268      *            the maximum capacity in characters

   269      * @param constraints

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

   271      * @param width

   272      *            the width of the bounding box, in pixels

   273      * @param rows

   274      *            the requested number of visible rows in the editor

   275      * @return Instance of TextEditor

   276      *

   277      * @throws IllegalArgumentException

   278      *             if <code>aMaxSize</code> or <code>aRows</code> is zero or

   279      *             less

   280      * @throws IllegalArgumentException

   281      *             if the value of the constraints parameter is invalid

   282      * @throws IllegalArgumentException

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

   284      *             capacity

   285      * @throws IllegalArgumentException

   286      *             if the width is less than one pixel

   287      */

   288     public static TextEditor createTextEditor(

   289         int maxSize,

   290         int constraints,

   291         int width,

   292         int rows)

   293     {

   294         return new TextEditorImpl(maxSize, constraints, width, rows);

   295     }

   296 

   297     /**

   298      * Sets this TextEditor focused or removes keyboard focus.

   299      * Calling setFocus(true) enables text editing from keys as the delivery

   300      * of needed key events will be targeted to the TextEditor instead of

   301      * the parent object (e.g. Canvas). Focus needs to be explicitly set to

   302      * the TextEditor by application. When Canvas or CustomItem does not have

   303      * any focused TextEditor all key and pointer events are delivered to

   304      * normal key delivery methods of parent. Necessary key events are

   305      * captured by TextEditor only when it has focus.

   306      * <P>

   307      * The setFocus affects to the parent key event delivery in following

   308      * way: If all TextEditors are unfocused the key event delivery of parent

   309      * works as if there are not any TextEditors in it, only when a focus is

   310      * set via this method to a TextEditor the key event delivery is modified.

   311      * The focused editor starts to capture the necessary key events and these

   312      * key events are not delivered to parent. The set of key events captured

   313      * depends on TextEditor implementation and device HW but in most

   314      * implementations nearly all device keys are captured by the editor for

   315      * text insertion, input mode changes and caret move functionalities.

   316      * Especially applications should not assume to get key events from keys

   317      * mapped to game actions as most probably the same keys are used to

   318      * navigate the text caret within the editor. The keys that are used for

   319      * Command launching in Canvas are available for applications on focused

   320      * TextEditor and these keys either launch commands or send low-level

   321      * key events as normally.

   322      * <P>

   323      * Setting focus does not cause any visual focus indication by the

   324      * implementation other than showing the caret. Any other change in the

   325      * visual appearance of the editor in focused state is the responsibility

   326      * of the application; this can be done for example by drawing a focus

   327      * border around the TextEditor or by changing the background color or

   328      * transparency of the editor.

   329      * <P>

   330      * If this TextEditor has already been focused earlier and the editor

   331      * contents has not changed after previous unfocusing, then after calling

   332      * setFocus again the caret position should be retained.

   333      * <P>

   334      * If there already is another focused TextEditor on the Canvas, the

   335      * focus is first removed from that TextEditor before setting this

   336      * TextEditor focused.

   337      * <P>

   338      * Calling setFocus(false) disables key based text editing and returns

   339      * the delivery of key events and pointer events to the underlying Canvas.

   340      *

   341      * @param focused

   342      *            keyboard focus of the TextEditor

   343      *

   344      * @throws java.lang.IllegalStateException

   345      *             If the TextEditor is not added to Canvas

   346      *

   347      * @see #hasFocus()

   348      */

   349 

   350     public void setFocus(boolean focused)

   351     {

   352         synchronized (iToolkit)

   353         {

   354             checkParent();

   355 

   356             // If focus is set, adjust the focus of other known editors.

   357             if (focused)

   358             {

   359                 // Remove focus from other editors in this parent

   360                 Enumeration editors = iEditorContainer.getEditors(iParent);

   361 

   362                 while (editors.hasMoreElements())

   363                 {

   364                     TextEditor editor = (TextEditor) editors.nextElement();

   365 

   366                     // Do not remove focus from this editor if it is on.

   367                     if (editor != this)

   368                     {

   369                         editor.setFocus(false);

   370                     }

   371                 }

   372             }

   373 

   374             NativeError.check(_setFocusState(getToolkitHandle(), iHandle,

   375                                              focused));

   376         }

   377     }

   378 

   379     /**

   380      * Returns the focus state of TextEditor.

   381      *

   382      * @return the focus state of the editor

   383      * @see #setFocus(boolean focused)

   384      */

   385     public boolean hasFocus()

   386     {

   387         boolean focusState;

   388 

   389         synchronized (iToolkit)

   390         {

   391             checkParent();

   392             focusState = _getFocusState(getToolkitHandle(), iHandle);

   393         }

   394 

   395         return focusState;

   396     }

   397 

   398     /**

   399      * Set the parent object of this <code>TextEditor</code>.

   400      * <P>

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

   402      * null removes the association to the parent. If

   403      * <code>setParent(null)</code> is called for a <code>TextEditor</code> yet

   404      * not having any parent or <code>setParent(parent)</code> is called with

   405      * the same parent, the call is silently ignored.

   406      * <P>

   407      *

   408      * @param parent

   409      *            the parent object

   410      *

   411      * @throws IllegalArgumentException

   412      *             if parent is not a valid object with which a

   413      *             <code>TextEditor</code> can be associated, or if CanvasItem

   414      *             is already set to another another parent

   415      */

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

   417     {

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

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

   420         // unsupported.

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

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

   423         {

   424             throw new IllegalArgumentException(ERROR_NOT_A_VALID_PARENT_OBJECT);

   425         }

   426 

   427         int parentHandle = 0;

   428 

   429         if (parent != iParent)

   430         {

   431             // Lock this object so that parent cannot be adjusted from

   432             // other threads.

   433             synchronized (iToolkit)

   434             {

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

   436                 if (parent instanceof Canvas)

   437                 {

   438                     // Note that canvas is shown inside a displayable so in

   439                     // this case we use the handle to the displayble object.

   440                     parentHandle = iToolkitInvoker.getDisplayableHandle(parent);

   441                 }

   442                 else if (parent instanceof CustomItem)

   443                 {

   444                     parentHandle = iToolkitInvoker.itemGetHandle(parent);

   445                 }

   446 

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

   448                 int error =

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

   450 

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

   452                 NativeError.check(error);

   453 

   454                 // Operation was successful. Store parent and register

   455                 // to container. Remove from container and previous parent.

   456                 if (iParent != null)

   457                 {

   458                     iEditorContainer.removeEditor(this, iParent);

   459                 }

   460                 // Store the editor with new parent if not null.

   461                 if (parent != null)

   462                 {

   463                     iEditorContainer.addEditor(this, parent);

   464                 }

   465 

   466                 iParent = parent;

   467             }

   468         }

   469     }

   470 

   471     /**

   472      * Sets the size of this <code>TextEditor</code> in pixels.

   473      *

   474      * @param width

   475      *            width in pixels

   476      * @param height

   477      *            height in pixels

   478      *

   479      * @throws IllegalArgumentException

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

   481      */

   482     public void setSize(int width, int height)

   483     {

   484         // Validate width and row count

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

   486         {

   487             throw new IllegalArgumentException(ERROR_GIVEN_ARGUMENTS_NOT_VALID);

   488         }

   489 

   490         synchronized (iToolkit)

   491         {

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

   493                                        height));

   494 

   495             // Operation was a success, store size.

   496             iWidth = width;

   497             iHeight = height;

   498         }

   499     }

   500 

   501     /**

   502      * <P>

   503      * Sets the rendering position of this <code>TextEditor</code>. The anchor

   504      * point given is relative to the upper left corner of the parent,

   505      * <code>Canvas</code>.

   506      * </P>

   507      *

   508      * <P>

   509      * The <code>TextEditor</code> may be placed fully off or partially of the

   510      * visible area of the parent, <code>Canvas</code>, by the

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

   512      * is just partly visible.

   513      * </P>

   514      *

   515      * @param x

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

   517      * @param y

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

   519      * @throws IllegalStateException

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

   521      * @see #setParent(java.lang.Object parent)

   522      */

   523     public void setPosition(int x, int y)

   524     {

   525         synchronized (iToolkit)

   526         {

   527             checkParent();

   528 

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

   530 

   531             // Store current position.

   532             iPositionX = x;

   533             iPositionY = y;

   534         }

   535     }

   536 

   537     /**

   538      * <P>

   539      * Sets the visibility value of <code>TextEditor</code>. Initially

   540      * <code>TextEditor</code> is not visible so it must be explicitly set to

   541      * visible in order it to appear on UI.

   542      * </P>

   543      *

   544      * <P>

   545      * Setting visibility to true shows the editor with its content, but without

   546      * the caret. If the editor does not have any visible content and does not

   547      * have any background color set then this method effectively does not cause

   548      * any visual change in the display. If the editor is already visible

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

   550      * </P>

   551      *

   552      * <P>

   553      * Setting the visibility to false hides the editor and its content. If the

   554      * <code>TextEditor</code> has focus then the focus is removed. If the

   555      * editor is already hidden calling <code>setVisible(false)</code> does

   556      * nothing.

   557      * </P>

   558      *

   559      * @param visible

   560      *            visibility of the <code>TextEditor</code>

   561      * @throws IllegalStateException

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

   563      * @see #setParent(java.lang.Object parent)

   564      */

   565     public void setVisible(boolean visible)

   566     {

   567         synchronized (iToolkit)

   568         {

   569             checkParent();

   570 

   571             NativeError

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

   573 

   574             iVisible = visible;

   575         }

   576     }

   577 

   578     /**

   579      * <P>

   580      * Sets the Z-position, or the elevation, of the item.

   581      * <p>

   582      * The elevation decides the stacking order of neighboring items. An item of

   583      * high Z-position will be drawn on top of an item with a lower Z-position

   584      * if they share the same parent item.

   585      * <p>

   586      * The z-position is unique for each item meaning that changing a Z-position

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

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

   589      * <p>

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

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

   592      * at that time.

   593      * </P>

   594      *

   595      * @param z

   596      *            the Z-position of the item.

   597      *

   598      * @throws IllegalArgumentException

   599      *             If <code>z</code> < 0

   600      * @throws IllegalStateException

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

   602      *

   603      * @see #getZPosition()

   604      * @see #setParent(java.lang.Object parent)

   605      */

   606     public void setZPosition(int z)

   607     {

   608         if (z < 0)

   609         {

   610             throw new IllegalArgumentException();

   611         }

   612 

   613         synchronized (iToolkit)

   614         {

   615             checkParent();

   616 

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

   618         }

   619     }

   620 

   621     /**

   622      * Specifies whether or not the editor will receive touch-events.

   623      * <p>

   624      * This is enabled by default.

   625      * An editor with touch-event disabled won't be able to perform any

   626      * touch-related functionality such as scrolling or positioning the

   627      * cursor. It may however still be controlled via the

   628      * virtual keypad/control-panel if that is enabled, or receive other +

   629      * input e.g. via physical keys

   630      * <p>

   631      * @param enabled

   632      *              true to enabled touch-event, false to disable

   633      */

   634     public void setTouchEnabled(boolean enabled)

   635     {

   636         if (iTouchEnabled != enabled)

   637         {

   638             synchronized (iToolkit)

   639             {

   640                 _setTouchEnabled(getToolkitHandle(), iHandle, enabled);

   641                 iTouchEnabled = enabled;

   642             }

   643         }

   644     }

   645 

   646     /**

   647      * Gets the current touch-enabled state

   648      * <p>

   649      * @return true if the editor is touch-enabled, false otherwise

   650      */

   651     public boolean isTouchEnabled()

   652     {

   653         return iTouchEnabled;

   654     }

   655 

   656     /**

   657      * <P>

   658      * Returns the Z-position, or the elevation, of the item. The Z-position

   659      * decides the stacking order of neighboring items.

   660      * </P>

   661      *

   662      * @return the Z-position of the item.

   663      *

   664      * @throws IllegalStateException

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

   666      *

   667      * @see #setZPosition(int)

   668      * @see #setParent(java.lang.Object parent)

   669      */

   670     public int getZPosition()

   671     {

   672         int positionZ = -1;

   673 

   674         synchronized (iToolkit)

   675         {

   676             checkParent();

   677 

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

   679         }

   680 

   681         NativeError.check(positionZ);

   682         return positionZ;

   683     }

   684 

   685     /**

   686      * Gets the line margin height in this <code>TextEditor</code> in pixels.

   687      * <p>

   688      * Gets the possible line margin height that editor has in addition to the

   689      * normal font height (<code>Font getHeight()</code>). The returned value is

   690      * 0 if the editor does not have any additional line margins to the text

   691      * height returned from <code>getHeight()</code> of Font set to the editor.

   692      * <p>

   693      *

   694      * @return the line margin height in pixels

   695      *

   696      * @see #setParent(java.lang.Object parent)

   697      */

   698     public int getLineMarginHeight()

   699     {

   700         int lineMarginHeight = 0;

   701 

   702         if (iParent != null)

   703         {

   704             synchronized (iToolkit)

   705             {

   706                 // Get the line margin height from the native side.

   707                 lineMarginHeight =

   708                     _getLineMarginHeight(getToolkitHandle(), iHandle);

   709             }

   710 

   711             // Check if the line margin height was not returned correctly.

   712             NativeError.check(lineMarginHeight);

   713         }

   714         return lineMarginHeight;

   715     }

   716 

   717     /**

   718      * Gets the whole content height in this <code>TextEditor</code> in pixels.

   719      * <p>

   720      *

   721      * The returned value must include the height of the whole content in the

   722      * editor, not just the height of the visible content.

   723      * <p>

   724      *

   725      * Note that the method returns 0, if the editor has no parent.

   726      * <p>

   727      *

   728      * @return the height of the whole content in the editor in pixels

   729      *

   730      * @see #setParent(java.lang.Object parent)

   731      */

   732     public int getContentHeight()

   733     {

   734         int contentHeight = 0;

   735         if (iParent != null)

   736         {

   737             synchronized (iToolkit)

   738             {

   739                 // Get the content height from the native side.

   740                 contentHeight = _getContentHeight(getToolkitHandle(), iHandle);

   741             }

   742 

   743             // Check if the size was not returned correctly.

   744             NativeError.check(contentHeight);

   745         }

   746         return contentHeight;

   747     }

   748 

   749     /**

   750      * <P>

   751      * Sets the index of the caret. The caret can be used to indicate a position

   752      * in the text.

   753      * </P>

   754      *

   755      * <P>

   756      * The Java platform implementation must scroll the content of the

   757      * <code>TextEditor</code> automatically so that the caret is within the

   758      * visible area. If the caret is set above the current position the content

   759      * should be scrolled so that the caret is on the top most visible row. If

   760      * the caret is set below the current position the content should be

   761      * scrolled so that the caret is on the lowest visible row.

   762      * </P>

   763      *

   764      * @param index

   765      *            the character index before which to place the caret

   766      *

   767      * @throws StringIndexOutOfBoundsException

   768      *             if <code>index</code> does not specify a valid range within

   769      *             the content of the <code>TextEditor</code>

   770      */

   771     public void setCaret(int index)

   772     {

   773         // New position must be in range of the current content.

   774         if (index < 0 || index > size())

   775         {

   776             throw new StringIndexOutOfBoundsException(

   777                 ERROR_GIVEN_ARGUMENTS_NOT_VALID);

   778         }

   779 

   780         synchronized (iToolkit)

   781         {

   782             NativeError.check(_setCaret(getToolkitHandle(), iHandle, index));

   783         }

   784     }

   785 

   786     /**

   787      * Gets the current position of the caret in the editor.

   788      *

   789      * @return the current caret position, <code>0</code> if at the beginning

   790      */

   791     public int getCaretPosition()

   792     {

   793         int caretPosition = 0;

   794 

   795         synchronized (iToolkit)

   796         {

   797             caretPosition = _getCaretPosition(getToolkitHandle(), iHandle);

   798         }

   799 

   800         // Verify that the operation was a success.

   801         NativeError.check(caretPosition);

   802         return caretPosition;

   803     }

   804 

   805     /**

   806      * <P>

   807      * Gets the topmost pixel position of the topmost visible line in the

   808      * editor.

   809      * </P>

   810      *

   811      * <P>

   812      * The returned y coordinate value is relative to the whole content height,

   813      * not just the visible part.

   814      * </P>

   815      *

   816      * <P>

   817      * This method can be used by the application together with the

   818      * <code>getContentHeight</code>, height of the font,

   819      * <code>getLineMarginHeight</code>, and <code>getCaretPosition</code>

   820      * methods in drawing custom visual cues like a scroll bar or other content

   821      * sensitive pop-ups.

   822      * </P>

   823      *

   824      * <P>

   825      * Note that the method returns 0, if the editor has no parent.

   826      * </P>

   827      *

   828      * @return the topmost pixel position of the visible content.

   829      */

   830     public int getVisibleContentPosition()

   831     {

   832         int ypos = 0;

   833 

   834         if (iParent != null)

   835         {

   836             synchronized (iToolkit)

   837             {

   838                 ypos = _getVisibleContentPosition(getToolkitHandle(), iHandle);

   839             }

   840 

   841             // Verify that the operation was a success.

   842             NativeError.check(ypos);

   843         }

   844         return ypos;

   845     }

   846 

   847     /**

   848      * <P>

   849      * Gets the font being used in rendering the text content in this

   850      * <code>TextEditor</code>.

   851      * </P>

   852      *

   853      * @return the font being used in this <code>TextEditor</code>

   854      */

   855     public Font getFont()

   856     {

   857         synchronized (iToolkit)

   858         {

   859             return iFont == null ? Font.getDefaultFont() : iFont;

   860         }

   861     }

   862 

   863     /**

   864      * <P>

   865      * Sets the application preferred font for rendering the text content in

   866      * this <code>TextEditor</code>. Setting the font is a hint to the

   867      * implementation, and the implementation may disregard the requested font.

   868      * </P>

   869      *

   870      * <P>

   871      * The <code>font</code> parameter must be a valid <code>Font</code> object

   872      * or <code>null</code>. If the <code>font</code> parameter is

   873      * <code>null</code>, the implementation must use its default font to render

   874      * the text content.

   875      * </P>

   876      *

   877      * @param font

   878      *            the application preferred font to be used in this

   879      *            <code>TextEditor</code>

   880      */

   881     public void setFont(Font font)

   882     {

   883         if (font == null)

   884         {

   885             font = Font.getDefaultFont();

   886         }

   887 

   888         int[] newSize = new int[2];

   889 

   890         synchronized (iToolkit)

   891         {

   892             NativeError.check(_setFont(getToolkitHandle(), iHandle,

   893                                        iLCDUIPackageInvoker.getFontHandle(font), newSize));

   894 

   895             iFont = font;

   896 

   897             iWidth = newSize[0];

   898             iHeight = newSize[1];

   899         }

   900     }

   901 

   902     /**

   903      * Gets the background color and alpha of this <code>TextEditor</code>.

   904      *

   905      * @return the background color

   906      */

   907     public int getBackgroundColor()

   908     {

   909         int color = 0;

   910 

   911         synchronized (iToolkit)

   912         {

   913             color = _getColor(getToolkitHandle(), iHandle,

   914                               COLOR_BACKGROUND);

   915         }

   916         return color;

   917     }

   918 

   919     /**

   920      * Gets the foreground color and alpha of this <code>TextEditor</code>

   921      *

   922      * @return the foreground color

   923      */

   924     public int getForegroundColor()

   925     {

   926         int color = 0;

   927 

   928         synchronized (iToolkit)

   929         {

   930             color = _getColor(getToolkitHandle(), iHandle,

   931                               COLOR_FOREGROUND);

   932         }

   933         return color;

   934     }

   935 

   936     /**

   937      * Sets the background color and alpha of this <code>TextEditor</code> to

   938      * the specified values. The default background color for editor is fully

   939      * transparent white.

   940      *

   941      * @param color

   942      *            the color

   943      */

   944     public void setBackgroundColor(int color)

   945     {

   946         int alpha = (color >> 24) & 0xff;

   947         int red   = (color >> 16) & 0xff;

   948         int green = (color >>  8) & 0xff;

   949         int blue  = (color) & 0xff;

   950 

   951         doSetColor(alpha, red, green, blue, COLOR_BACKGROUND);

   952     }

   953 

   954     /**

   955      * Sets the foreground color and alpha of this <code>TextEditor</code> to

   956      * the specified values. The content, e.g. text, in the editor must be drawn

   957      * with this color. The default foreground color is fully opaque black.

   958      *

   959      * @param color

   960      *            the color

   961      */

   962     public void setForegroundColor(int color)

   963     {

   964         int alpha = (color >> 24) & 0xff;

   965         int red   = (color >> 16) & 0xff;

   966         int green = (color >>  8) & 0xff;

   967         int blue  = (color) & 0xff;

   968 

   969         doSetColor(alpha, red, green, blue, COLOR_FOREGROUND);

   970     }

   971 

   972     /**

   973      * Sets the highlight background color. This impacts text background color

   974      * for the selected text.

   975      * The text in a current selection range will be

   976      * rendered using given color value. The default highlight background

   977      * color is fully opaque black.

   978      *

   979      * This method is not supported on S40 platform.

   980      *

   981      * @param color

   982      *            the color

   983      */

   984     public void setHighlightBackgroundColor(int color)

   985     {

   986         int alpha = (color >> 24) & 0xff;

   987         int red   = (color >> 16) & 0xff;

   988         int green = (color >>  8) & 0xff;

   989         int blue  = (color) & 0xff;

   990 

   991         doSetColor(alpha, red, green, blue, COLOR_HIGHLIGHT_BACKGROUND);

   992     }

   993 

   994     /**

   995      * Sets the highlight foreground color. This impacts text color for the

   996      * selected text.

   997      * The text in a current selection range will be rendered

   998      * using given color value. The default highlight foreground color is fully

   999      * opaque white.

  1000      *

  1001      * This method is not supported on S40 platform.

  1002      *

  1003      * @param color

  1004      *            the color

  1005      */

  1006     public void setHighlightForegroundColor(int color)

  1007     {

  1008         int alpha = (color >> 24) & 0xff;

  1009         int red   = (color >> 16) & 0xff;

  1010         int green = (color >>  8) & 0xff;

  1011         int blue  = (color) & 0xff;

  1012 

  1013         doSetColor(alpha, red, green, blue, COLOR_HIGHLIGHT_FOREGROUND);

  1014     }

  1015 

  1016     /**

  1017      * Sets the content of the <code>TextEditor</code> as a string. The set

  1018      * string replaces any previous content in the editor.

  1019      *

  1020      * @param content

  1021      *            the new content of the <code>TextEditor</code> as string,

  1022      *            <code>null</code> empties the <code>TextEditor</code>

  1023      *

  1024      * @throws IllegalArgumentException

  1025      *             if <code>aContent</code> is illegal for the current input

  1026      *             constraints

  1027      * @throws IllegalArgumentException

  1028      *             if the given text would exceed the current maximum capacity

  1029      *             of the editor

  1030      */

  1031     public void setContent(String content)

  1032     {

  1033         // Verify that text is not invalid.

  1034         iLCDUIPackageInvoker.checkText(content, iMaxSize);

  1035 

  1036         synchronized (iToolkit)

  1037         {

  1038             NativeError

  1039             .check(_setContent(getToolkitHandle(), iHandle, content));

  1040         }

  1041     }

  1042 

  1043     /**

  1044      * Gets the string content in the <code>TextEditor</code>.

  1045      *

  1046      * @return The editor current content

  1047      */

  1048     public String getContent()

  1049     {

  1050         String content = null;

  1051         int[] error = new int[1];

  1052 

  1053         synchronized (iToolkit)

  1054         {

  1055             content = _getContent(getToolkitHandle(), iHandle, error);

  1056         }

  1057 

  1058         NativeError.check(error[0]);

  1059         return content;

  1060     }

  1061 

  1062     /**

  1063      * <P>

  1064      * Inserts a string into the content of the <code>TextEditor</code>.

  1065      * </P>

  1066      *

  1067      * <P>

  1068      * The string is inserted just prior to the character indicated by the

  1069      * <code>position</code> parameter, where zero specifies the first character

  1070      * of the content in the <code>TextEditor</code>. If <code>position</code>

  1071      * is less than or equal to zero, the insertion occurs at the beginning of

  1072      * the content. If <code>position</code> is greater than or equal to the

  1073      * current size of the content, the insertion occurs immediately after the

  1074      * end of the content.

  1075      * </P>

  1076      *

  1077      * <P>

  1078      * The current size of the contents is increased by the number of inserted

  1079      * characters. The resulting string must fit within the current maximum

  1080      * capacity.

  1081      * </P>

  1082      *

  1083      * @param text

  1084      *            the <code>String</code> to be inserted

  1085      * @param position

  1086      *            the position at which insertion is to occur

  1087      *

  1088      * @throws IllegalArgumentException

  1089      *             if the resulting content would be illegal for the current

  1090      *             input constraints

  1091      * @throws IllegalArgumentException

  1092      *             if the insertion would exceed the current maximum capacity

  1093      * @throws NullPointerException

  1094      *             if <code>text</code> is <code>null</code>

  1095      */

  1096     public void insert(String text, int position)

  1097     {

  1098         // Check illegal arguments. Note that NullPointerException is thrown

  1099         // correctly if text is null when text.length() is called.

  1100         if (text.length() + size() > iMaxSize)

  1101         {

  1102             throw new IllegalArgumentException(ERROR_GIVEN_ARGUMENTS_NOT_VALID);

  1103         }

  1104 

  1105         synchronized (iToolkit)

  1106         {

  1107             NativeError.check(_insert(getToolkitHandle(), iHandle, text,

  1108                                       position));

  1109         }

  1110     }

  1111 

  1112     /**

  1113      * <P>

  1114      * Deletes characters from the <code>TextEditor</code>.

  1115      * </P>

  1116      *

  1117      * <P>

  1118      * The <code>offset</code> and <code>length</code> parameters must specify a

  1119      * valid range of characters within the contents of the

  1120      * <code>TextEditor</code>. The <code>offset</code> parameter must be within

  1121      * the range <code>[0..(size())]</code>, inclusive. The <code>length</code>

  1122      * parameter must be a non-negative integer such that

  1123      * <code>(offset + length) &lt;= size()</code>.

  1124      * </P>

  1125      *

  1126      * @param offset

  1127      *            the beginning of the region to be deleted

  1128      * @param length

  1129      *            the number of characters to be deleted

  1130      *

  1131      * @throws IllegalArgumentException

  1132      *             if the resulting contents would be illegal for the current

  1133      *             input constraints

  1134      * @throws StringIndexOutOfBoundsException