source: trunk/src/gcc/libjava/java/awt/im/InputContext.java@ 1389

Last change on this file since 1389 was 1389, checked in by bird, 22 years ago

Initial revision
  • Property cvs2svn:cvs-rev set to 1.1
  • Property svn:eol-style set to native
  • Property svn:executable set to *
File size: 15.2 KB
Line 
1/* InputContext.java -- provides the context for text input
2 Copyright (C) 2002, 2003 Free Software Foundation, Inc.
3
4This file is part of GNU Classpath.
5
6GNU Classpath is free software; you can redistribute it and/or modify
7it under the terms of the GNU General Public License as published by
8the Free Software Foundation; either version 2, or (at your option)
9any later version.
10
11GNU Classpath is distributed in the hope that it will be useful, but
12WITHOUT ANY WARRANTY; without even the implied warranty of
13MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14General Public License for more details.
15
16You should have received a copy of the GNU General Public License
17along with GNU Classpath; see the file COPYING. If not, write to the
18Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
1902111-1307 USA.
20
21Linking this library statically or dynamically with other modules is
22making a combined work based on this library. Thus, the terms and
23conditions of the GNU General Public License cover the whole
24combination.
25
26As a special exception, the copyright holders of this library give you
27permission to link this library with independent modules to produce an
28executable, regardless of the license terms of these independent
29modules, and to copy and distribute the resulting executable under
30terms of your choice, provided that you also meet, for each linked
31independent module, the terms and conditions of the license of that
32module. An independent module is a module which is not derived from
33or based on this library. If you modify this library, you may extend
34this exception to your version of the library, but you are not
35obligated to do so. If you do not wish to do so, delete this
36exception statement from your version. */
37
38package java.awt.im;
39
40import java.awt.AWTEvent;
41import java.awt.AWTException;
42import java.awt.Component;
43import java.awt.im.spi.InputMethod;
44import java.awt.im.spi.InputMethodDescriptor;
45import java.io.BufferedReader;
46import java.io.InputStreamReader;
47import java.io.IOException;
48import java.net.URL;
49import java.net.URLConnection;
50import java.util.ArrayList;
51import java.util.Enumeration;
52import java.util.HashMap;
53import java.util.Locale;
54import gnu.java.util.EmptyEnumeration;
55
56/**
57 * Provides a context for controlling input methods and keyboard layouts.
58 * This class provides the communication layer between the client component,
59 * and the various locale-dependent text entry input methods that can be used
60 * for the client. By default, there is one instance per Window, shared among
61 * all components, but this limits text entry to one component at a time.
62 * Thus, text components can create their own instance to allow text entry
63 * in multiple components at a time.
64 *
65 * <p>By using the interfaces of {@link java.awt.im.spi}, you can install
66 * extensions which allow additional input methods. Some of these may use
67 * platform native input methods, or keyboard layouts provided by the platform.
68 * Input methods are unavailable if none have been installed and the platform
69 * has no underlying native input methods. Extensions are installed as jar
70 * files, usually accessed in the default extension location or specified by
71 * the -extdir VM flag. The jar must contain a file named
72 * "META_INF/services/java.awt.im.spi.InputMethodDescriptor" which lists,
73 * one entry per line in UTF-8 encoding, each class in the jar that implements
74 * java.awt.im.spi.InputMethodDescriptor.
75 *
76 * @author Eric Blake <[email protected]>
77 * @see Component#getInputContext()
78 * @see Component#enableInputMethods(boolean)
79 * @since 1.2
80 * @status updated to 1.4, but unverified
81 */
82public class InputContext
83{
84 /**
85 * The list of installed input method descriptors.
86 */
87 private static final ArrayList descriptors = new ArrayList();
88 static
89 {
90 Enumeration enum;
91 try
92 {
93 enum = ClassLoader.getSystemResources
94 ("META_INF/services/java.awt.im.spi.InputMethodDescriptor");
95 }
96 catch (IOException ex)
97 {
98 // XXX Should we do something else?
99 enum = EmptyEnumeration.getInstance();
100 }
101 while (enum.hasMoreElements())
102 {
103 URL url = (URL) enum.nextElement();
104 BufferedReader in;
105 String line;
106 try
107 {
108 in = new BufferedReader
109 (new InputStreamReader(url.openConnection().getInputStream(),
110 "UTF-8"));
111 line = in.readLine().trim();
112 }
113 catch (IOException ignored)
114 {
115 continue;
116 }
117 outer:
118 while (line != null)
119 {
120 try
121 {
122 if (line.charAt(0) != '#')
123 {
124 Class c = Class.forName(line);
125 descriptors.add((InputMethodDescriptor) c.newInstance());
126 }
127 line = in.readLine().trim();
128 }
129 catch (IOException e)
130 {
131 continue outer;
132 }
133 catch (Exception ignored)
134 {
135 }
136 }
137 }
138 }
139
140 /** The current input method; null if no input methods are installed. */
141 private InputMethod im;
142
143 /** Map of locales to the most recently selected input method. */
144 private final HashMap recent = new HashMap();
145
146 /** The list of acceptable character subsets. */
147 private Character.Subset[] subsets;
148
149 /**
150 * Construct an InputContext. This is protected, so clients must use
151 * {@link #getInstance()} instead.
152 */
153 protected InputContext()
154 {
155 }
156
157 /**
158 * Returns a new InputContext.
159 *
160 * @return a new instance, initialized to the default locale if available
161 */
162 public static InputContext getInstance()
163 {
164 InputContext ic = new InputContext();
165 ic.selectInputMethod(Locale.getDefault());
166 return ic;
167 }
168
169 /**
170 * Attempts to select an input method or keyboard layout which supports the
171 * given locale. This returns true if a locale is available and was selected.
172 * The following steps are taken in choosing an input method:<ul>
173 * <li>If the currently selected input method or keyboard layout supports
174 * the requested locale, it remains selected.</li>
175 * <li>If there is no input method or keyboard layout available that
176 * supports the requested locale, the current input method or keyboard
177 * layout remains selected.</li>
178 * <li>If the user has previously selected an input method or keyboard
179 * layout for the requested locale from the user interface, then the most
180 * recently selected such input method or keyboard layout is reselected.</li>
181 * <li>Otherwise, an input method or keyboard layout that supports the
182 * requested locale is selected in an implementation dependent way. This
183 * implementation chooses the first input method which supports the requested
184 * locale based on the InputMethodDescriptors loaded from the extensions
185 * installed on the CLASSPATH.</li>
186 * </ul>
187 *
188 * <p>Before switching away from an input method, any currently uncommitted
189 * text is committed. Not all host operating systems provide API to
190 * determine the locale of the currently selected native input method or
191 * keyboard layout, and to select a native input method or keyboard layout
192 * by locale. For host operating systems that don't provide such API,
193 * selectInputMethod assumes that native input methods or keyboard layouts
194 * provided by the host operating system support only the system's default
195 * locale.
196 *
197 * <p>An example of where this may be called is in a multi-language document,
198 * when moving the insertion point between sections of different locale, so
199 * that the user may use the input method appropriate to that section of the
200 * document.
201 *
202 * @param locale the desired new locale
203 * @return true if the new locale is active
204 * @throws NullPointerException if locale is null
205 */
206 public boolean selectInputMethod(Locale locale)
207 {
208 if (im != null && im.setLocale(locale))
209 {
210 recent.put(locale, im);
211 return true;
212 }
213 InputMethod next = (InputMethod) recent.get(locale);
214 outer:
215 if (next != null)
216 for (int i = 0, limit = descriptors.size(); i < limit; i++)
217 {
218 InputMethodDescriptor d = (InputMethodDescriptor) descriptors.get(i);
219 Locale[] list;
220 try
221 {
222 list = d.getAvailableLocales();
223 }
224 catch (AWTException ignored)
225 {
226 continue;
227 }
228 for (int j = list.length; --j >= 0; )
229 if (locale.equals(list[j]))
230 {
231 try
232 {
233 next = d.createInputMethod();
234 recent.put(locale, next);
235 }
236 catch (Exception ignored)
237 {
238 continue;
239 }
240 }
241 }
242 if (next == null)
243 return false;
244 // XXX I'm not sure if this does all the necessary steps in the switch.
245 if (im != null)
246 {
247 try
248 {
249 next.setCompositionEnabled(im.isCompositionEnabled());
250 }
251 catch (UnsupportedOperationException ignored)
252 {
253 }
254 im.endComposition();
255 im.deactivate(false);
256 im.hideWindows();
257 }
258 im = next;
259 im.setLocale(locale);
260 im.setCharacterSubsets(subsets);
261 return true;
262 }
263
264 /**
265 * Returns the current locale of the current input method or keyboard
266 * layout. Returns null if the input context does not have a current input
267 * method or keyboard layout or if the current input method's
268 * {@link InputMethod#getLocale()} method returns null. Not all host
269 * operating systems provide API to determine the locale of the currently
270 * selected native input method or keyboard layout. For host operating
271 * systems that don't provide such API, getLocale assumes that the current
272 * locale of all native input methods or keyboard layouts provided by the
273 * host operating system is the system's default locale.
274 *
275 * @return the locale of the current input method, or null
276 * @since 1.3
277 */
278 public Locale getLocale()
279 {
280 return im == null ? null : im.getLocale();
281 }
282
283 /**
284 * Sets the subsets of Unicode characters allowed to be input by the current
285 * input method, as well as subsequent input methods. The value of null
286 * implies all characters are legal. Applications should not rely on this
287 * behavior, since native host input methods may not allow restrictions.
288 * If no current input method is available, this has no immediate effect.
289 *
290 * @param subsets the set of Unicode subsets to accept, or null
291 */
292 public void setCharacterSubsets(Character.Subset[] subsets)
293 {
294 this.subsets = subsets;
295 if (im != null)
296 im.setCharacterSubsets(subsets);
297 }
298
299 /**
300 * Changes the enabled status of the current input method. An input method
301 * that is enabled for composition interprets incoming events for both
302 * composition and control purposes, while a disabled input method only
303 * interprets control commands (including commands to enable itself).
304 *
305 * @param enable whether to enable the input method
306 * @throws UnsupportedOperationException if there is no current input method,
307 * or the input method does not support enabling
308 * @see #isCompositionEnabled()
309 * @since 1.3
310 */
311 public void setCompositionEnabled(boolean enable)
312 {
313 if (im == null)
314 throw new UnsupportedOperationException();
315 im.setCompositionEnabled(enable);
316 }
317
318 /**
319 * Find out if the current input method is enabled.
320 *
321 * @return true if the current input method is enabled
322 * @throws UnsupportedOperationException if there is no current input method,
323 * or the input method does not support enabling
324 * @see #setCompositionEnabled(boolean)
325 * @since 1.3
326 */
327 public boolean isCompositionEnabled()
328 {
329 if (im == null)
330 throw new UnsupportedOperationException();
331 return im.isCompositionEnabled();
332 }
333
334 /**
335 * Starts a reconversion operation in the current input method. The input
336 * method gets theh text to reconvert from the client component, using
337 * {@link InputMethodRequests#getSelectedText(Attribute[])}. Then the
338 * composed and committed text produced by the operation is sent back to
339 * the client using a sequence of InputMethodRequests.
340 *
341 * @throws UnsupportedOperationException if there is no current input method,
342 * or the input method does not support reconversion
343 * @since 1.3
344 */
345 public void reconvert()
346 {
347 if (im == null)
348 throw new UnsupportedOperationException();
349 im.reconvert();
350 }
351
352 /**
353 * Dispatches an event to the current input method. This is called
354 * automatically by AWT. If no input method is available, then the event
355 * will never be consumed.
356 *
357 * @param event the event to dispatch
358 * @throws NullPointerException if event is null
359 */
360 public void dispatchEvent(AWTEvent event)
361 {
362 if (im != null)
363 im.dispatchEvent(event);
364 }
365
366 /**
367 * Notifies the input context that a client component has been removed from
368 * its containment hierarchy, or that input method support has been disabled
369 * for the component. This method is usually called from the client
370 * component's {@link Component#removeNotify()} method. Potentially pending
371 * input from input methods for this component is discarded. If no input
372 * methods are available, then this method has no effect.
373 *
374 * @param client the client component
375 * @throws NullPointerException if client is null
376 */
377 public void removeNotify(Component client)
378 {
379 // XXX What to do with client information?
380 if (im != null)
381 {
382 im.deactivate(false);
383 im.removeNotify();
384 }
385 }
386
387 /**
388 * Ends any input composition that may currently be going on in this
389 * context. Depending on the platform and possibly user preferences, this
390 * may commit or delete uncommitted text. Any changes to the text are
391 * communicated to the active component using an input method event. If no
392 * input methods are available, then this method has no effect. This may
393 * be called for a variety of reasons, such as when the user moves the
394 * insertion point in the client text outside the range of the composed text,
395 * or when text is saved to file.
396 */
397 public void endComposition()
398 {
399 if (im != null)
400 im.endComposition();
401 }
402
403 /**
404 * Disposes of the input context and release the resources used by it.
405 * Called automatically by AWT for the default input context of each
406 * Window. If no input methods are available, then this method has no
407 * effect.
408 */
409 public void dispose()
410 {
411 if (im != null)
412 {
413 im.deactivate(false);
414 im.dispose();
415 }
416 }
417
418 /**
419 * Returns a control object from the current input method, or null. A
420 * control object provides implementation-dependent methods that control
421 * the behavior of the input method or obtain information from the input
422 * method. Clients have to compare the result against known input method
423 * control object types. If no input methods are available or the current
424 * input method does not provide an input method control object, then null
425 * is returned.
426 *
427 * @return the control object, or null
428 */
429 public Object getInputMethodControlObject()
430 {
431 return im == null ? null : im.getControlObject();
432 }
433} // class InputContext
Note: See TracBrowser for help on using the repository browser.