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