--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/javauis/lcdui_akn/javalcdui/javasrc.nokialcdui/com/nokia/mid/ui/S40TextEditor.java Thu Aug 19 09:48:13 2010 +0300
@@ -0,0 +1,322 @@
+/*
+ * 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;
+
+/**
+ * <p>
+ * This interfaces provides access to extended editing-related functionality, that is only
+ * available on Series 40 devices.</p>
+ * <b>Commands:</b><br>
+ * Applications can use {@link com.nokia.mid.ui.S40TextEditor#getTextEditorCommands()} and {@link com.nokia.mid.ui.S40TextEditor#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 <code>launchTextEditorCommand(cmd, COMMAND_MODE_KEYPRESS)</code> for the "Clear"-command will cause
+ * to editor to keep deleting characters until the application calls <code>launchTextEditorCommand(cmd, COMMAND_MODE_KEYRELEASE)</code>.
+ * 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 Series 40 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;
+
+ /**
+ * Constant for Cursor Wrap Off
+ * No cursor wrapping occurs.
+ * Traverse out callback is active for up / down
+ * Traverse out callback is active for left / right when the editor is empty.
+ */
+ public static final int CURSOR_WRAP_OFF = 0;
+
+ /**
+ * Constant for Cursor Wrap Left/Right
+ * Cursor wrapping is active only for left / right.
+ * Traverse out callback is supported for up / down.
+ */
+ public static final int CURSOR_WRAP_LEFT_RIGHT = 2;
+
+ /**
+ * Constant for Cursor Wrap Full
+ * Cursor wrapping is active for all directions (up / down / left / right).
+ * Doesnt send traverse out callback.
+ */
+ public static final int CURSOR_WRAP_FULL = 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 com.nokia.mid.ui.S40TextEditor#launchTextEditorCommand(Command, int)}-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 = 0x00010000;
+
+ /**
+ * Indicates that the user tries to exit this TextEditor left.
+ * This action is only generated when the cursor wrap mode is set to {@link #CURSOR_WRAP_OFF} and the editor
+ * is empty.
+ */
+ public static final int ACTION_TRAVERSE_LEFT = 0x00020000;
+
+ /**
+ * Indicates that the user tries to exit this TextEditor right.
+ * This action is only generated when the cursor wrap mode is set to {@link #CURSOR_WRAP_OFF} and the editor
+ * is empty.
+ */
+ public static final int ACTION_TRAVERSE_RIGHT = 0x00040000;
+
+// native_const(JAVA_TEXTEDITOR)
+// {
+
+ /**
+ * 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=1;
+
+ /**
+ * 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=2;
+
+ /**
+ * constant value to indicate full visibility of a TextEditor
+ */
+ public static final int VISIBLE=3;
+
+
+ /**
+ * 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=1;
+
+ /**
+ * 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=2;
+
+ /**
+ * Specifies the current input mode of this TextEditor
+ * @param mode the new input-mode. This should be a value returned by {@link com.nokia.mid.ui.S40TextEditor#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 com.nokia.mid.ui.S40TextEditor#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 com.nokia.mid.ui.S40TextEditor#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 com.nokia.mid.ui.S40TextEditor#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 com.nokia.mid.ui.S40TextEditor#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);
+
+ /**
+ * Specifies the Cursor Wrap setting. This is required to allow the canvas editor to change state so
+ * that left / right cursor keys are able to traverse out of the editor if the editor is empty.
+ * @param wrap new cursor wrap setting
+ */
+ public void setCursorWrap(int wrap);
+
+ /**
+ * Gets the current Cursor Wrap setting
+ * @return current cursor wrap setting
+ */
+ public int getCursorWrap();
+
+}