/*

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

 * All rights reserved.

 * This component and the accompanying materials are made available

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

 * which accompanies this distribution, and is available

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

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description: Public class defining the interface for MIDP Text Editor

 *

 */

// PACKAGE

package com.nokia.mid.ui;

// INTERNAL IMPORTS

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

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

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

// EXTERNAL IMPORTS

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

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

import com.nokia.mid.ui.CanvasItem;

import javax.microedition.lcdui.Font;

import javax.microedition.lcdui.Canvas;

import javax.microedition.lcdui.CustomItem;

import javax.microedition.lcdui.TextField;

import java.util.Enumeration;

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

/**

 * <P>

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

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

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

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

 * </P>

 *

 * <P>

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

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

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

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

 * blinking, is handled by the TextEditor implementation.

 * </P>

 *

 * <P>

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

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

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

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

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

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

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

 * </P>

 *

 * <P>

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

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

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

 * </P>

 *

 * <P>

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

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

 * line break characters.

 * </P>

 *

 * <P>

 * The TextEditor provides necessary interaction for example for touch input

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

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

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

 * parent completely.

 * </P>

 *

 * <P>

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

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

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

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

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

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

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

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

 * the implementation actually moves the caret in the editor.

 * </P>

 *

 * <P>

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

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

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

 * </P>

 *

 * <P>

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

 * visible TextEditor.

 * </P>

 *

 * <P>

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

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

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

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

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

 * is left to the application.

 * </P>

 *

 * @since 1.4

 */

public class TextEditor

        extends CanvasItem

{

    // Protected data for extending classes.

    // LCDUI Toolkit object.

    Object iToolkit;

    // Native handle

    int iHandle;

    // LCDUI package invoker.

    LCDUIPackageInvoker iLCDUIPackageInvoker;

    // Change listener. May be NULL.

    TextEditorListenerImpl iListener;

    // Private data

    // LCDUI Toolkit invoker object.

    private ToolkitInvoker iToolkitInvoker;

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

    private int iConstraints;

    // Initial input mode

    private java.lang.String iCharacterSubset;

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

    private int iMaxSize;

    // The current font of this text editor component

    private Font iFont;

    // Text editor container for handling editor focusing.

    private static TextEditorContainer iEditorContainer;

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

    private static final int COLOR_BACKGROUND = 0;

    private static final int COLOR_FOREGROUND = 1;

    private static final int COLOR_HIGHLIGHT_BACKGROUND = 2;

    private static final int COLOR_HIGHLIGHT_FOREGROUND = 3;

    // The maximum value for all colors.

    private static final int COLOR_MAX_VALUE = 255;

    // Static block for creating editor container.

    static

    {

        iEditorContainer = new TextEditorContainer();

    }

    private Finalizer mFinalizer;

    /**

     * <P>

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

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

     * pixels.

     * </P>

     *

     * <P>

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

     * is created empty.

     * </P>

     *

     * <P>

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

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

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

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

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

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

     * order to fit, and no exception is thrown.

     * </P>

     *

     * <P>

     * </P>

     *

     * @param text

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

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

     * @param maxSize

     *            the maximum capacity in characters

     * @param constraints

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

     * @param width

     *            the width of the bounding box, in pixels

     * @param height

     *            the height of the bounding box, in pixels

     * @return Instance of TextEditor

     *

     * @throws IllegalArgumentException

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

     * @throws IllegalArgumentException

     *             if the value of the constraints parameter is invalid

     * @throws IllegalArgumentException

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

     *             constraints

     * @throws IllegalArgumentException

     *             if the length of the string exceeds the requested maximum

     *             capacity

     * @throws IllegalArgumentException

     *             if the width or height is less than one pixel

     */

    public static TextEditor createTextEditor(

        String text,

        int maxSize,

        int constraints,

        int width,

        int height)

    {

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

    }

    /**

     * <P>

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

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

     * </P>

     *

     * <P>

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

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

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

     * </P>

     *

     * <P>

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

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

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

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

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

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

     * order to fit, and no exception is thrown.

     * </P>

     *

     * <P>

     * </P>

     *

     * @param maxSize

     *            the maximum capacity in characters

     * @param constraints

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

     * @param width

     *            the width of the bounding box, in pixels

     * @param rows

     *            the requested number of visible rows in the editor

     * @return Instance of TextEditor

     *

     * @throws IllegalArgumentException

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

     *             less

     * @throws IllegalArgumentException

     *             if the value of the constraints parameter is invalid

     * @throws IllegalArgumentException

     *             if the length of the string exceeds the requested maximum

     *             capacity

     * @throws IllegalArgumentException

     *             if the width is less than one pixel

     */

    public static TextEditor createTextEditor(

        int maxSize,

        int constraints,

        int width,

        int rows)

    {

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

    }

    /**

     * Sets this TextEditor focused or removes keyboard focus.

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

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

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

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

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

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

     * captured by TextEditor only when it has focus.

     * <P>

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

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

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

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

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

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

     * depends on TextEditor implementation and device HW but in most

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

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

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

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

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

     * Command launching in Canvas are available for applications on focused

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

     * key events as normally.

     * <P>

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

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

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

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

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

     * transparency of the editor.

     * <P>

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

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

     * setFocus again the caret position should be retained.

     * <P>

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

     * focus is first removed from that TextEditor before setting this

     * TextEditor focused.

     * <P>

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

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

     *

     * @param focused

     *            keyboard focus of the TextEditor

     *

     * @throws java.lang.IllegalStateException

     *             If the TextEditor is not added to Canvas

     *

     * @see #hasFocus()

     */

    public void setFocus(boolean focused)

    {

        synchronized (iToolkit)

        {

            checkParent();

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

            if (focused)

            {

                // Remove focus from other editors in this parent

                Enumeration editors = iEditorContainer.getEditors(iParent);

                while (editors.hasMoreElements())

                {

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

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

                    if (editor != this)

                    {

                        editor.setFocus(false);

                    }

                }

            }

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

                                             focused));

        }

    }

    /**

     * Returns the focus state of TextEditor.

     *

     * @return the focus state of the editor

     * @see #setFocus(boolean focused)

     */

    public boolean hasFocus()

    {

        boolean focusState;

        synchronized (iToolkit)

        {

            checkParent();

            focusState = _getFocusState(getToolkitHandle(), iHandle);

        }

        return focusState;

    }

    /**

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

     * <P>

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

     * null removes the association to the parent. If

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

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

     * the same parent, the call is silently ignored.

     * <P>

     *

     * @param parent

     *            the parent object

     *

     * @throws IllegalArgumentException

     *             if parent is not a valid object with which a

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

     *             is already set to another another parent

     */

    public void setParent(java.lang.Object parent)

    {

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

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

        // unsupported.

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

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

        {

            throw new IllegalArgumentException(ERROR_NOT_A_VALID_PARENT_OBJECT);

        }

        int parentHandle = 0;

        if (parent != iParent)

        {

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

            // other threads.

            synchronized (iToolkit)

            {

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

                if (parent instanceof Canvas)

                {

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

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

                    parentHandle = iToolkitInvoker.getDisplayableHandle(parent);

                }

                else if (parent instanceof CustomItem)

                {

                    parentHandle = iToolkitInvoker.itemGetHandle(parent);

                }

                // parentHandle = 0 indicates removal of the parent.

                int error =

                    _setParent(getToolkitHandle(), iHandle, parentHandle);

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

                NativeError.check(error);

                // Operation was successful. Store parent and register

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

                if (iParent != null)

                {

                    iEditorContainer.removeEditor(this, iParent);

                }

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

                if (parent != null)

                {

                    iEditorContainer.addEditor(this, parent);

                }

                iParent = parent;

            }

        }

    }

    /**

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

     *

     * @param width

     *            width in pixels

     * @param height

     *            height in pixels

     *

     * @throws IllegalArgumentException

     *             if the width or height is less than one pixel

     */

    public void setSize(int width, int height)

    {

        // Validate width and row count

        if (width < 1 || height < 1)

        {

            throw new IllegalArgumentException(ERROR_GIVEN_ARGUMENTS_NOT_VALID);

        }

        synchronized (iToolkit)

        {

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

                                       height));

            // Operation was a success, store size.

            iWidth = width;

            iHeight = height;

        }

    }

    /**

     * <P>

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

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

     * <code>Canvas</code>.

     * </P>

     *

     * <P>

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

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

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

     * is just partly visible.

     * </P>

     *

     * @param x

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

     * @param y

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

     * @throws IllegalStateException

     *             if a valid parent object has not been set.

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

     */

    public void setPosition(int x, int y)

    {

        synchronized (iToolkit)

        {

            checkParent();

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

            // Store current position.

            iPositionX = x;