--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/javauis/lcdui_akn/javalcdui/javasrc.nokialcdui/com/nokia/mid/ui/S40TextEditor.java Tue Apr 27 16:30:29 2010 +0300
@@ -0,0 +1,320 @@
+/*
+ * 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);
+}