javauis/lcdui_akn/javalcdui/javasrc.nokialcdui/com/nokia/mid/ui/S60TextEditor.java
/*
* 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 S60 Text Editor
*
*/
// PACKAGE
package com.nokia.mid.ui;
/**
* <P>
* S60 platform specific extensions to <code>TextEditor</code>. These methods
* are only available in Java Runtime for Symbian.
* </P>
*
* <P>
* <code>TextEditor</code> does not support DSA over its area. Playing video or
* using camera over <code>TextEditor</code> area can lead to artifacts on
* screen.
* </P>
*
* <h3>Editing state indicators</h3>
* <p>
* By default, the implementation uses platform specific indicators for the
* <code>
* TextEditor</code>. Typically these indicators are shown in the status pane
* and the visibility is related to the focus of the associated
* <code>TextEditor</code>. When the associated editor is focused, the platform
* displays the editing state indicators for the user and when focus is lost
* from the editor the indicators are hidden.
* </p>
* <p>
* The application can also choose to control the input indicators if needed. In
* this case, the visibility and position needs to be controlled separately when
* focusing the associated editor. It should be noted that if no indicators are
* shown to the user, the usability maybe diminished especially with complex
* input methods.
* </p>
* <p>
* When using custom indicator position, the background color of the indicator
* area is equal to the associated <code>TextEditor</code>'s background color.
* </p>
*
* <h3>Touch input methods</h3>
* <p>
* The application has a possibility to control the touch input methods with
* this class. It is possible to set the disabled touch input modes and the
* preferred touch mode if needed. It must be noted that supported touch input
* modes depend on the used device thus some of the touch modes cannot be set as
* preferred or enabled.
* </p>
*
* <h3>Touch screen virtual keyboard</h3>
* <p>
* In touch-only devices when user taps on a text editor touch screen
* virtual keyboard is opened. The keyboard takes part of the screen space, so
* canvas is smaller when virtual keyboard is visible.
* Application is notified about this by events, so it can react on this
* change and resize, move TextEditor to the visible area and adjust the
* whole Canvas.
* </p>
* @see TextEditor
* @since 1.4
*/
public abstract interface S60TextEditor
{
/**
* Indicates that all input methods are available.
* <p>
* Can be used in {@link #setDisabledTouchInputModes}.
*/
public static final int TOUCH_INPUT_ALL_AVAILABLE = 0;
/**
* Handwriting recognition
*/
public static final int TOUCH_INPUT_HWR = 1;
/**
* Virtual QWERTY keyboard
*/
public static final int TOUCH_INPUT_VKB = 2;
/**
* Full screen QWERTY keyboard
*/
public static final int TOUCH_INPUT_FSQ = 4;
/**
* Alphanumeric keyboard with ITU-T input
*/
public static final int TOUCH_INPUT_ITUT = 8;
/**
* Full screen handwriting recognition
*/
public static final int TOUCH_INPUT_FSC = 16;
/**
* Mini ITU-T for Japanese devices
*/
public static final int TOUCH_INPUT_MINI_ITUT = 32;
/**
* Indicates that the touch screen virtual keyboard is opened.
*/
public static final int ACTION_VIRTUAL_KEYBOARD_OPEN = 0x1000;
/**
* Indicates that the touch screen virtual keyboard is closed.
*/
public static final int ACTION_VIRTUAL_KEYBOARD_CLOSE = 0x2000;
/**
* <P>
* If the default indicator location is not used then sets the drawing
* location for input indicators relative to the <code>TextEditor</code>'s
* parent.
* </P>
*
* <P>
* The anchor point given is relative to the upper left corner of the
* <code>Canvas</code>. The location may be outside the
* <code>TextEditor</code> boundaries. The z-order of the indicators is the
* same as <code>TextEditor</code> textual content. If indicators and the
* editor content overlap indicators are rendered on top of the editor
* content.
* </P>
*
* <P>
* The application should first query the size of the input indicators with
* {@link #getIndicatorSize} method to determine that the indicators will
* not be clipped outside the available display area when drawn to the
* requested location.
* </P>
*
* <P>
* If there are no indicators present, the usability of complex device
* specific input methods may be compromised.
* </P>
*
* @param x
* the x coordinate of the anchor point, in pixels.
* @param y
* the y coordinate of the anchor point, in pixels.
*
*/
public void setIndicatorLocation(int x, int y);
/**
* <P>
* Resets the implementation provided input indicators to their default
* position.
* </P>
*
* <P>
* This position may be outside the area of parent in case the default
* position is in status area. In this case if the status area is missing
* (full screen mode Canvas) the default position is inside the parent area
* e.g. on top of the editor. When default position is in use the
* <code>TextEditor</code> automatically positions the indicators relative
* to the <code>TextEditor</code> even when <code>TextEditor</code> location
* is changed. However, client is responsible of making sure indicators are
* visible inside the parent area positioning <code>TextEditor</code> so
* that indicators fit to the visible area e.g. on top of the
* <code>TextEditor</code>. Positioning <code>TextEditor</code> directly on
* top of <code>Canvas</code> may mean that indicators in the default
* position are not visible.
* </P>
*
* @throws IllegalStateException
* If the <code>TextEditor</code> is not added to
* <code>Canvas</code>
*/
public void setDefaultIndicators();
/**
* <P>
* By default indicators visibility is set to <code>true</code> and they are
* made visible when the associated <code>TextEditor</code> is focused.
* </P>
* <P>
* If the application controls the position of the indicators, those can be
* explicitly made not visible by calling
* <code>setIndicatorVisibility(false)</code>. Indicators are never visible
* if <code>TextEditor</code> itself is not visible so having indicator
* visibility set to <code>true</code> does not make them visible unless
* editor itself is set visible.
* </P>
*
* @param visible
* controls indicator visibility state
*
* @see #setIndicatorLocation(int, int)
* @see #setDefaultIndicators()
*/
public void setIndicatorVisibility(boolean visible);
/**
* Gets the size of the area needed for drawing the input indicators.
* <p>
* The returned array contains two integers for width (array index 0) and
* height (array index 1) of the indicator graphics. Size (0,0) is returned
* if the device UI does not use any input indicators in the text editors or
* if the indicators are curretly positioned outside parent area e.g. in
* status area. This happens if {@link #setIndicatorLocation(int, int)
* setIndicatorLocation(int x, int y)} has not been ever called for the
* editor, or if {@link #setDefaultIndicators() setDefaultIndicators()} has
* been called.
* <p>
*
* @return the width and height of area needed for drawing input indicators
* @see #setDefaultIndicators()
*/
public int[] getIndicatorSize();
/**
* Disables one or multiple touch input modes from use.
* <p>
* User is not able to switch to the disable touch input modes. Multiple
* touch input modes may be combined together in <code>touchInputMode</code>
* parameter using bitwise or operator. The method does not have any impact
* if called in non-touch device. A device may not support all touch input
* modes specified. Specifying not supported input modes is silently
* ignored.
* <p>
* The possible values are defined in the class with TOUCH_INPUT_* starting
* constant values.
* <p>
*
* @param touchInputModes
* bitwise or combined list of disabled touch input modes
* @throws IllegalArgumentException
* if the given input modes are not valid.
* <p>
* @see #setPreferredTouchMode(int)
* @see #getDisabledTouchInputModes()
*/
public void setDisabledTouchInputModes(int touchInputModes);
/**
* By default all supported touch input modes are available. Returns the
* disabled touch input modes set with {@link #setDisabledTouchInputModes}.
* <p>
* Note that the disabled touch input modes may be device specific so this
* method may return some modes as disabled by default.
* <p>
* Note that if the device does not support touch input this method returns
* all modes.
* <p>
*
* @return The disabled touch input modes.
* @see #setDisabledTouchInputModes(int)
* @see #setPreferredTouchMode(int)
*/
public int getDisabledTouchInputModes();
/**
* Set the preferred touch input mode overriding the device default
* preferred mode. User may still change the touch input mode from touch
* input window to all available modes.
* <p>
* The possible values are defined in the class with TOUCH_INPUT_* starting
* constant values.
* <p>
* Note that if the device does not support touch input this method has no
* effect.
* <p>
*
* @param touchInputModes
* a touch input mode to be set as preferred one.
* @throws IllegalArgumentException
* if the input mode is not valid or if it contains multiple
* input modes as bit mask.
* @see #setDisabledTouchInputModes(int)
* @see #getPreferredTouchMode()
*
*/
public void setPreferredTouchMode(int touchInputModes);
/**
* Gets the preferred touch input mode.
* <p>
* Note that if the device does not support touch input this method returns
* <code>0</code>
* <p>
*
* @return The preferred touch input mode.
* <p>
* @see #setPreferredTouchMode(int)
* @see #setDisabledTouchInputModes(int)
*/
public int getPreferredTouchMode();
/**
* Sets the caret in the Editor at x, y location.
*
* @param x
* The x coordinate of the wanted caret position.
*
* @param y
* The y coordinate of the wanted caret position.
*/
public void setCaretXY(int x, int y);
}
// End of file