- * Commands:
- * 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
- * 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 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.
- * 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);
-}