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