/*
 * 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:  Interface for S40 Text Editor
 *
 */

package com.nokia.mid.ui;

import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.Image;

/**
 * This interfaces provides access to extended editing-related functionality,
 *  that is only available on s40-devices:<p>
 * <b>Commands:</b><br>
 * Applications can use {@link TextEditor#getTextEditorCommands()} and
 * {@link TextEditor#launchTextEditorCommand(Command, int)} to present
 * editing-commands in a customized way. When launching such a command,
 * the application has to specify a command-mode. This is because some commands
 * may require information regarding the key-state that has caused this command
 * to be launched. For example, calling
 * launchTextEditorCommand(cmd, COMMAND_MODE_KEYPRESS) for the "Clear"-command
 * will cause to editor to keep deleting characters until the application calls
 * launchTextEditorCommand(cmd, COMMAND_MODE_KEYRELEASE). Since not all commands
 * require keystate-information, applications can use
 * {@link com.nokia.mid.ui.S40TextEditor #isCommandKeyWanted(Command)}
 * If no command-key is wanted, COMMAND_MODE_SELECTED should be passed
 * when launching this command <p>
 * <b>Indicator-icons</b><br>
 * It is possible to access the indicator-icons that the platform would normally
 * display as Images, using
 * {@link com.nokia.mid.ui.S40TextEditor #getIndicatorIcons()} <p>
 * <b>Visibility</b><br>
 * Applications may be in the situation where they want an editor to be visible,
 * but to not process keys or be animated, e.g. while a custom options-menu
 * is displayed. In those cases, it is possible to call
 * {@link com.nokia.mid.ui.S40TextEditor #setVisible(int)} <p>
 * <b>Extra properties</b><br>
 * Some properties that are not available in the com.nokia.mid.ui.TextEditor,
 * like writing-direction, native emoticon support and positioning for native
 * popup-windows.  <p>
 * On s40-devices this interface is implemented by the object returned by
 * {@link com.nokia.mid.ui.TextEditor#createTextEditor(String, int, int, int,
 * int)} if the MIDlet is manufacturer- or operator-signed
 *
 */
public abstract interface S40TextEditor
{

    /**
     * command type used to indicate commands
     * that should be put on the middle softkey
     */
    public final static int SELECT_SOFTKEY_COMMAND = 9;

    /**
     * command type used to indicate commands
     * that should be put on the right softkey.
     */
    public final static int RIGHT_SOFTKEY_COMMAND = 10;

    /**
     * command type used to indicate commands
     * that should be put as the last one in the option list.
     */
    public final static int LAST_IN_OPTIONS_COMMAND = 12;

    /**
     * command type used to indicate commands
     * that should be put on the left softkey.
     */
    public final static int LEFT_SOFTKEY_COMMAND = 13;


    /**
     * constant for left-to-right direction
     */
    public static final int DIRECTION_LTR = 0;

    /**
     * constant for right-to-left direction
     */
    public static final int DIRECTION_RTL = 1;

    /**
     * Event that indicates that the applications options-list should be closed.
     * The implementation sends this even in a case where the platform
     * has displayed further nested options as the result
     * of a {@link TextEditor#launchTextEditorCommand(Command)}-call.
     * If the user selects one of the nested options (e.g. "copy"),
     * the platform will carry out the associated functionality, dismiss
     * the native options-popup  and send the ACTION_OPTIONS_CLOSED-event,
     * in order to indicate that any options-list that the application
     * might have displayed should also be closed.
     *
     */
    public static final int ACTION_OPTIONS_CLOSED = 0x200;

    /**
     * Event that indicates a change in the position of this editor. Typically
     * one (or both) of the values last returned by
     * {@link com.nokia.mid.ui.TextEditor#getContentHeight()} and
     * {@link com.nokia.mid.ui.TextEditor#getVisibleContentPosition()}
     * will have changed after this event.
     *
     */
    public static final int ACTION_SCROLLBAR_CHANGED = 0x400;

    /**
     * Indicates that the text in this TextEditor is masked according to the
     * Oz Mobile Password Masking Scheme
     */
    public static final int PASSWORD_MASKED = 0x400000;

    /**
     * Indicates that the text in this TextEditor is locked according to the
     * Oz Mobile Password Masking Scheme
     */
    public static final int PASSWORD_LOCKED = 0x800000;

    /**
     * constant value to indicate a hidden/invisible TextEditor
     */
    public static final int HIDDEN=0;

    /**
     * constant value to indicate partial visibility of a TextEditor.
     * A partially visible TextEditor will still be displayed, but not
     * receive any key-events, and not have a blinking cursor
     */
    public static final int PARTIALLY_VISIBLE=0;

    /**
     * constant value to indicate full visibility of a TextEditor
     */
    public static final int VISIBLE=0;


    /**
     * Command-mode to indicate that a command is launched without
     * keystate-information, e.g. from an options-menu
     */
    public static final int COMMAND_MODE_SELECTED=0;

    /**
     * Command-mode to indicate that a command is launched with a keypress,
     * e.g. by pressing RSK
     */
    public static final int COMMAND_MODE_KEYPRESS=0;

    /**
     * Command-mode to indicate that a command has been launched
     * with a keypress, and that this key has now been released,
     * e.g. by releasing the RSK
     */
    public static final int COMMAND_MODE_KEYRELEASE=0;

    /**
     * Specifies the current input mode of this TextEditor
     * @param mode the new input-mode. This should be a value returned by
     *     {@link TextEditor#getInputMode()}
     */
    public void setInputMode(int mode) throws IllegalArgumentException;

    /**
     * Gets the current input mode of this TextEditor
     * @return the current input mode. This value represents a native
     * input-mode, that can be passed to {@link TextEditor#setInputMode(int)}
     *
     */
    public int getInputMode();

    /**
     * Returns the current set of Editor-Commands
     * @return the commands
     */
    public Command[] getTextEditorCommands();



    /**
     * Executes an editor-option. This method will invoke native functionality
     * according to the command. This may be an action in the editor
     * (copy, delete,..) which then in turn will cause callbacks to this editors
     * TextEditorListener. It may as well cause platform-controlled panels
     * (nested options, touch-dialog) to cover part of or the full display. <br>
     * This method should be called from inside the keyPressed()-method.
     * @param cmd The command to launch. This has to be a command returned by
     *     {@link TextEditor#getTextEditorCommands()}
     * @return true if launching this command has displayed a list of further
     *      sub-commands as a popup. if an application has displayed
     *      an options-menu before launching a command, this options-menu
     *      should normally stay on the screen after this launch, to indicate
     *      that the native sub-commands are nested and related to the command
     *      that has been launched.
     *
     * @throws IllegalStateException if the TextEditor is not focussed during
     *      this call
     * @throws IllegalArgumentException if the command is not available
     *      in the editor. Commands that are available in the editor are only
     *      those that this editor has provided via
     *      {@link TextEditor#getTextEditorCommands()}
     */
    public boolean launchTextEditorCommand(Command cmd,int mode)
    throws IllegalStateException, IllegalArgumentException;

    /**
     * Gets the menu-state of a Command
     * @param cmd The Command to query for Menu-state. This has to be a command
     *      returned by {@link TextEditor#getTextEditorCommands()}
     * @return true if this a Menu Command. Launching a Menu Command will show
     *      a popup on the display, providing further commands to the user
     */
    public boolean isMenuCommand(Command cmd);

    /**
     * Returns whether a command requires keystate-information to be launched.
     * @param cmd The command to be queried
     * @return true if cmd requires keystate-information. In this case,
     *      one of COMMAND_MODE_KEYPRESS or COMMAND_MODE_KEYRELEASE should be
     *      passed when launching this command via
     *      {@link com.nokia.mid.ui.S40TextEditor #launchTextEditorCommand(
     *      Command, int)} false if cmd does not require keystate-informationl.
     *      In that case, COMMAND_MODE_SELECTED should be passed
     *      when launching it.
     */
    public boolean isCommandKeyWanted(Command cmd);


    /**
     * Specifies the amount of pixels by which the TextEditor will scroll text
     * horizontally, if multiline input is disabled.
     * @param offset The scrolling offset. When a cursor-movement requires
     *      horizontal scrolling of the text, this value indicates by how many
     *      pixels the text will be moved.
     */
    public void setHorizontalScrollingWidth(int offset);

    /**
     * Gets the current horizontal scrolling width
     * @return the scrolling width
     */
    public int getHorizontalScrollingWidth();

    /**
     * Gets the current writing-direction
     * @return DIRECTION_LTR or DIRECTION_RTL
     */
    public int getWritingDirection();

    /**
     * Gets the current indicator-icons as images
     * @return the icons
     */
    public Image[] getIndicatorIcons();

    /**
     * Specifies the visibility of this TextEditor.
     * In some cases, for example when an application wants to display a custom
     * Options-Menu, the method
     * {@link com.nokia.mid.ui.TextEditor#setVisible(boolean)}
     * may not be sufficient. For this purpose, this method allows to specify
     * a partial visibility, which will display the TextEditor without
     * e.g. animating the curosr, an in which the application can receive
     * the key-events from the Canvas.
     * @param visible the type of the visibility.
     *      Has to be one of VISIBLE,PARTIALLY_VISIBLE or HIDDEN. Calling this
     *      method with VISIBLE has the same effect as calling
     *      {@link com.nokia.mid.ui.TextEditor#setVisible(boolean)} with true,
     *      HIDDEN as with false.
     * @throws IllegalArgumentException if visible has an unspecified value
     */
    public void setVisible(int visible) throws IllegalArgumentException;

    /**
     * Specifies whether emoticons should be available for this editor.
     * If not enabled, the implementation will not provide any facilities
     * to insert emoticons, e.g. via commands or special character-dialog,
     * itself
     * @param enable true to enable emoticons, false to disable
     */
    public void enableEmoticons(boolean enable);

    /**
     * Gets the emoticons-state of this editor
     * @return true if emoticons are enabled, false if not
     */
    public boolean isEnableEmoticons();

    /**
     * Specifies a position on the screen where native popups will be displayed.
     * This is a hint to the implementation, that may be disregarded.
     * @param x x-coordinate of the popups position
     * @param y y-coordinate of the popups position
     */
    public void setPopupPosition(int x,int y);

    /**
     * Specifies prefix and postfix text to be displayed along with the actual
     * editor-content. This text will not be part of the actual editor-buffer,
     * and hence can't be edited, and will not be considered by methods like
     * {@link com.nokia.mid.ui.TextEditor#size()}
     * @param prefix text to be displayed before the actual content.
     *      May be null to disable prefix-text
     * @param postfix text to be displayed after the actual content.
     *      May be null to disable postfix-text
     */
    public void setFixedText(String prefix,String postfix);
}