1 /* |
|
2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Interface for S40 Text Editor |
|
15 * |
|
16 */ |
|
17 |
|
18 package com.nokia.mid.ui; |
|
19 |
|
20 import javax.microedition.lcdui.Command; |
|
21 import javax.microedition.lcdui.Image; |
|
22 |
|
23 /** |
|
24 * <p> |
|
25 * This interfaces provides access to extended editing-related functionality, that is only |
|
26 * available on Series 40 devices.</p> |
|
27 * <b>Commands:</b><br> |
|
28 * Applications can use {@link com.nokia.mid.ui.S40TextEditor#getTextEditorCommands()} and {@link com.nokia.mid.ui.S40TextEditor#launchTextEditorCommand(Command, int)} |
|
29 * to present editing-commands in a customized way. When launching such a command, the application has to specify a |
|
30 * command-mode. This is because some commands may require information regarding the key-state that has caused this command to |
|
31 * be launched. For example, calling <code>launchTextEditorCommand(cmd, COMMAND_MODE_KEYPRESS)</code> for the "Clear"-command will cause |
|
32 * to editor to keep deleting characters until the application calls <code>launchTextEditorCommand(cmd, COMMAND_MODE_KEYRELEASE)</code>. |
|
33 * Since not all commands require keystate-information, applications can use {@link com.nokia.mid.ui.S40TextEditor#isCommandKeyWanted(Command)} |
|
34 * If no command-key is wanted, COMMAND_MODE_SELECTED should be passed when launching this command <p> |
|
35 * <b>Indicator-icons</b><br> |
|
36 * It is possible to access the indicator-icons that the platform would normally display as Images, using |
|
37 * {@link com.nokia.mid.ui.S40TextEditor#getIndicatorIcons()} <p> |
|
38 * <b>Visibility</b><br> |
|
39 * 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 |
|
40 * a custom options-menu is displayed. In those cases, it is possible to call {@link com.nokia.mid.ui.S40TextEditor#setVisible(int)} <p> |
|
41 * <b>Extra properties</b><br> |
|
42 * Some properties that are not available in the com.nokia.mid.ui.TextEditor, like writing-direction, native emoticon support |
|
43 * and positioning for native popup-windows. <p> |
|
44 * 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 |
|
45 * the MIDlet is manufacturer or operator signed. |
|
46 * |
|
47 */ |
|
48 public abstract interface S40TextEditor { |
|
49 |
|
50 /** |
|
51 * command type used to indicate commands |
|
52 * that should be put on the middle softkey |
|
53 */ |
|
54 public final static int SELECT_SOFTKEY_COMMAND = 9; |
|
55 |
|
56 /** |
|
57 * command type used to indicate commands |
|
58 * that should be put on the right softkey. |
|
59 */ |
|
60 public final static int RIGHT_SOFTKEY_COMMAND = 10; |
|
61 |
|
62 /** |
|
63 * command type used to indicate commands |
|
64 * that should be put as the last one in the option list. |
|
65 */ |
|
66 public final static int LAST_IN_OPTIONS_COMMAND = 12; |
|
67 |
|
68 /** |
|
69 * command type used to indicate commands |
|
70 * that should be put on the left softkey. |
|
71 */ |
|
72 public final static int LEFT_SOFTKEY_COMMAND = 13; |
|
73 |
|
74 |
|
75 /** |
|
76 * constant for left-to-right direction |
|
77 */ |
|
78 public static final int DIRECTION_LTR = 0; |
|
79 |
|
80 /** |
|
81 * constant for right-to-left direction |
|
82 */ |
|
83 public static final int DIRECTION_RTL = 1; |
|
84 |
|
85 /** |
|
86 * Constant for Cursor Wrap Off |
|
87 * No cursor wrapping occurs. |
|
88 * Traverse out callback is active for up / down |
|
89 * Traverse out callback is active for left / right when the editor is empty. |
|
90 */ |
|
91 public static final int CURSOR_WRAP_OFF = 0; |
|
92 |
|
93 /** |
|
94 * Constant for Cursor Wrap Left/Right |
|
95 * Cursor wrapping is active only for left / right. |
|
96 * Traverse out callback is supported for up / down. |
|
97 */ |
|
98 public static final int CURSOR_WRAP_LEFT_RIGHT = 2; |
|
99 |
|
100 /** |
|
101 * Constant for Cursor Wrap Full |
|
102 * Cursor wrapping is active for all directions (up / down / left / right). |
|
103 * Doesnt send traverse out callback. |
|
104 */ |
|
105 public static final int CURSOR_WRAP_FULL = 1; |
|
106 |
|
107 /** |
|
108 * Event that indicates that the applications options-list should be closed. |
|
109 * The implementation sends this even in a case where the platform has displayed further |
|
110 * nested options as the result of a {@link com.nokia.mid.ui.S40TextEditor#launchTextEditorCommand(Command, int)}-call. |
|
111 * If the user selects one of the nested options (e.g. "copy"), the platform will carry out the |
|
112 * associated functionality, dismiss the native options-popup and send the |
|
113 * ACTION_OPTIONS_CLOSED-event, in order to indicate that any options-list that the application |
|
114 * might have displayed should also be closed. |
|
115 * |
|
116 */ |
|
117 public static final int ACTION_OPTIONS_CLOSED = 0x00010000; |
|
118 |
|
119 /** |
|
120 * Indicates that the user tries to exit this TextEditor left. |
|
121 * This action is only generated when the cursor wrap mode is set to {@link #CURSOR_WRAP_OFF} and the editor |
|
122 * is empty. |
|
123 */ |
|
124 public static final int ACTION_TRAVERSE_LEFT = 0x00020000; |
|
125 |
|
126 /** |
|
127 * Indicates that the user tries to exit this TextEditor right. |
|
128 * This action is only generated when the cursor wrap mode is set to {@link #CURSOR_WRAP_OFF} and the editor |
|
129 * is empty. |
|
130 */ |
|
131 public static final int ACTION_TRAVERSE_RIGHT = 0x00040000; |
|
132 |
|
133 // native_const(JAVA_TEXTEDITOR) |
|
134 // { |
|
135 |
|
136 /** |
|
137 * Indicates that the text in this TextEditor is masked according to the |
|
138 * Oz Mobile Password Masking Scheme |
|
139 */ |
|
140 public static final int PASSWORD_MASKED = 0x400000; |
|
141 |
|
142 /** |
|
143 * Indicates that the text in this TextEditor is locked according to the |
|
144 * Oz Mobile Password Masking Scheme |
|
145 */ |
|
146 public static final int PASSWORD_LOCKED = 0x800000; |
|
147 // } |
|
148 |
|
149 /** |
|
150 * constant value to indicate a hidden/invisible TextEditor |
|
151 */ |
|
152 public static final int HIDDEN=1; |
|
153 |
|
154 /** |
|
155 * constant value to indicate partial visibility of a TextEditor. |
|
156 * A partially visible TextEditor will still be displayed, but not |
|
157 * receive any key-events, and not have a blinking cursor |
|
158 */ |
|
159 public static final int PARTIALLY_VISIBLE=2; |
|
160 |
|
161 /** |
|
162 * constant value to indicate full visibility of a TextEditor |
|
163 */ |
|
164 public static final int VISIBLE=3; |
|
165 |
|
166 |
|
167 /** |
|
168 * Command-mode to indicate that a command is launched without keystate-information, e.g. from |
|
169 * an options-menu |
|
170 */ |
|
171 public static final int COMMAND_MODE_SELECTED=0; |
|
172 |
|
173 /** |
|
174 * Command-mode to indicate that a command is launched with a keypress, e.g. by pressing RSK |
|
175 */ |
|
176 public static final int COMMAND_MODE_KEYPRESS=1; |
|
177 |
|
178 /** |
|
179 * Command-mode to indicate that a command has been launched with a keypress, and that this key |
|
180 * has now been released, e.g. by releasing the RSK |
|
181 */ |
|
182 public static final int COMMAND_MODE_KEYRELEASE=2; |
|
183 |
|
184 /** |
|
185 * Specifies the current input mode of this TextEditor |
|
186 * @param mode the new input-mode. This should be a value returned by {@link com.nokia.mid.ui.S40TextEditor#getInputMode()} |
|
187 */ |
|
188 public void setInputMode(int mode) throws IllegalArgumentException; |
|
189 |
|
190 /** |
|
191 * Gets the current input mode of this TextEditor |
|
192 * @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)} |
|
193 * |
|
194 */ |
|
195 public int getInputMode(); |
|
196 |
|
197 /** |
|
198 * Returns the current set of Editor-Commands |
|
199 * @return the commands |
|
200 */ |
|
201 public Command[] getTextEditorCommands(); |
|
202 |
|
203 /** |
|
204 * Executes an editor-option. This method will invoke native functionality according to the command. This may |
|
205 * be an action in the editor (copy, delete,..) which then in turn will cause callbacks to this editors |
|
206 * TextEditorListener. It may as well cause platform-controlled panels (nested options, touch-dialog) to cover part of |
|
207 * or the full display. <br> |
|
208 * This method should be called from inside the keyPressed()-method. |
|
209 * @param cmd The command to launch. This has to be a command returned by {@link com.nokia.mid.ui.S40TextEditor#getTextEditorCommands()} |
|
210 * @return true if launching this command has displayed a list of further sub-commands as a popup. if an application |
|
211 * has displayed an options-menu before launching a command, this options-menu should normally stay on the screen |
|
212 * after this launch, to indicate that the native sub-commands are nested and related to the command that has been |
|
213 * launched. |
|
214 * |
|
215 * @throws IllegalStateException if the TextEditor is not focussed during this call |
|
216 * @throws IllegalArgumentException if the command is not available in the editor. Commands that are |
|
217 * available in the editor are only those that this editor has provided via {@link com.nokia.mid.ui.S40TextEditor#getTextEditorCommands()} |
|
218 */ |
|
219 public boolean launchTextEditorCommand(Command cmd,int mode) throws IllegalStateException, IllegalArgumentException; |
|
220 |
|
221 /** |
|
222 * Gets the menu-state of a Command |
|
223 * @param cmd The Command to query for Menu-state. This has to be a command returned by {@link com.nokia.mid.ui.S40TextEditor#getTextEditorCommands()} |
|
224 * @return true if this a Menu Command. Launching a Menu Command will show a popup on the display, providing further |
|
225 * commands to the user |
|
226 */ |
|
227 public boolean isMenuCommand(Command cmd); |
|
228 |
|
229 /** |
|
230 * Returns whether a command requires keystate-information to be launched. |
|
231 * @param cmd The command to be queried |
|
232 * @return true if cmd requires keystate-information. In this case, one of COMMAND_MODE_KEYPRESS or COMMAND_MODE_KEYRELEASE |
|
233 * should be passed when launching this command via {@link com.nokia.mid.ui.S40TextEditor#launchTextEditorCommand(Command, int)} |
|
234 * false if cmd does not require keystate-informationl. In that case, COMMAND_MODE_SELECTED should be passed when launching it. |
|
235 */ |
|
236 public boolean isCommandKeyWanted(Command cmd); |
|
237 |
|
238 |
|
239 /** |
|
240 * Specifies the amount of pixels by which the TextEditor will scroll text horizontally, if multiline |
|
241 * input is disabled. |
|
242 * @param offset The scrolling offset. When a cursor-movement requires horizontal scrolling of the |
|
243 * text, this value indicates by how many pixels the text will be moved. |
|
244 */ |
|
245 public void setHorizontalScrollingWidth(int offset); |
|
246 |
|
247 /** |
|
248 * Gets the current horizontal scrolling width |
|
249 * @return the scrolling width |
|
250 */ |
|
251 public int getHorizontalScrollingWidth(); |
|
252 |
|
253 /** |
|
254 * Gets the current writing-direction |
|
255 * @return DIRECTION_LTR or DIRECTION_RTL |
|
256 */ |
|
257 public int getWritingDirection(); |
|
258 |
|
259 /** |
|
260 * Gets the current indicator-icons as images |
|
261 * @return the icons |
|
262 */ |
|
263 public Image[] getIndicatorIcons(); |
|
264 |
|
265 /** |
|
266 * Specifies the visibility of this TextEditor. |
|
267 * In some cases, for example when an application wants to display a custom Options-Menu, the method |
|
268 * {@link com.nokia.mid.ui.TextEditor#setVisible(boolean)} may not be sufficient. For this purpose, |
|
269 * this method allows to specify a partial visibility, which will display the TextEditor without |
|
270 * e.g. animating the curosr, an in which the application can receive the key-events from the Canvas. |
|
271 * @param visible the type of the visibility. Has to be one of VISIBLE,PARTIALLY_VISIBLE or HIDDEN. |
|
272 * Calling this method with VISIBLE has the same effect as calling {@link com.nokia.mid.ui.TextEditor#setVisible(boolean)} |
|
273 * with true, HIDDEN as with false. |
|
274 * @throws IllegalArgumentException if visible has an unspecified value |
|
275 */ |
|
276 public void setVisible(int visible) throws IllegalArgumentException; |
|
277 |
|
278 /** |
|
279 * Specifies whether emoticons should be available for this editor. If not enabled, the implementation |
|
280 * will not provide any facilities to insert emoticons, e.g. via commands or special character-dialog, |
|
281 * itself |
|
282 * @param enable true to enable emoticons, false to disable |
|
283 */ |
|
284 public void enableEmoticons(boolean enable); |
|
285 |
|
286 /** |
|
287 * Gets the emoticons-state of this editor |
|
288 * @return true if emoticons are enabled, false if not |
|
289 */ |
|
290 public boolean isEnableEmoticons(); |
|
291 |
|
292 /** |
|
293 * Specifies a position on the screen where native popups will be displayed. This is a hint to the |
|
294 * implementation, that may be disregarded. |
|
295 * @param x x-coordinate of the popups position |
|
296 * @param y y-coordinate of the popups position |
|
297 */ |
|
298 public void setPopupPosition(int x,int y); |
|
299 |
|
300 /** |
|
301 * Specifies prefix and postfix text to be displayed along with the actual editor-content. |
|
302 * This text will not be part of the actual editor-buffer, and hence can't be edited, and will not |
|
303 * be considered by methods like {@link com.nokia.mid.ui.TextEditor#size()} |
|
304 * @param prefix text to be displayed before the actual content. May be null to disable prefix-text |
|
305 * @param postfix text to be displayed after the actual content. May be null to disable postfix-text |
|
306 */ |
|
307 public void setFixedText(String prefix,String postfix); |
|
308 |
|
309 /** |
|
310 * Specifies the Cursor Wrap setting. This is required to allow the canvas editor to change state so |
|
311 * that left / right cursor keys are able to traverse out of the editor if the editor is empty. |
|
312 * @param wrap new cursor wrap setting |
|
313 */ |
|
314 public void setCursorWrap(int wrap); |
|
315 |
|
316 /** |
|
317 * Gets the current Cursor Wrap setting |
|
318 * @return current cursor wrap setting |
|
319 */ |
|
320 public int getCursorWrap(); |
|
321 |
|
322 } |
|