- * This interfaces provides access to extended editing-related functionality, that is only - * available on Series 40 devices.
- * Commands: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
- * Indicator-icons
- * It is possible to access the indicator-icons that the platform would normally display as Images, using
- * {@link com.nokia.mid.ui.S40TextEditor#getIndicatorIcons()}
- * Visibility
- * 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)}
- * Extra properties
- * 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.
- * 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.
- * 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();
-
-}