001/* InputContext.java -- provides the context for text input 002 Copyright (C) 2002, 2003, 2004, 2005 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038 039package java.awt.im; 040 041import gnu.java.util.EmptyEnumeration; 042 043import java.awt.AWTEvent; 044import java.awt.AWTException; 045import java.awt.Component; 046import java.awt.im.spi.InputMethod; 047import java.awt.im.spi.InputMethodDescriptor; 048import java.io.BufferedReader; 049import java.io.IOException; 050import java.io.InputStreamReader; 051import java.net.URL; 052import java.text.AttributedCharacterIterator.Attribute; 053import java.util.ArrayList; 054import java.util.Enumeration; 055import java.util.HashMap; 056import java.util.Locale; 057 058/** 059 * Provides a context for controlling input methods and keyboard layouts. 060 * This class provides the communication layer between the client component, 061 * and the various locale-dependent text entry input methods that can be used 062 * for the client. By default, there is one instance per Window, shared among 063 * all components, but this limits text entry to one component at a time. 064 * Thus, text components can create their own instance to allow text entry 065 * in multiple components at a time. 066 * 067 * <p>By using the interfaces of {@link java.awt.im.spi}, you can install 068 * extensions which allow additional input methods. Some of these may use 069 * platform native input methods, or keyboard layouts provided by the platform. 070 * Input methods are unavailable if none have been installed and the platform 071 * has no underlying native input methods. Extensions are installed as jar 072 * files, usually accessed in the default extension location or specified by 073 * the -extdir VM flag. The jar must contain a file named 074 * "META_INF/services/java.awt.im.spi.InputMethodDescriptor" which lists, 075 * one entry per line in UTF-8 encoding, each class in the jar that implements 076 * java.awt.im.spi.InputMethodDescriptor. 077 * 078 * @author Eric Blake (ebb9@email.byu.edu) 079 * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 080 * @see Component#getInputContext() 081 * @see Component#enableInputMethods(boolean) 082 * @since 1.2 083 * @status updated to 1.4, but unverified 084 */ 085public class InputContext 086{ 087 /** 088 * The list of installed input method descriptors. 089 */ 090 private static final ArrayList<InputMethodDescriptor> descriptors 091 = new ArrayList<InputMethodDescriptor>(); 092 093 static 094 { 095 Enumeration e; 096 try 097 { 098 e = ClassLoader.getSystemResources 099 ("META_INF/services/java.awt.im.spi.InputMethodDescriptor"); 100 } 101 catch (IOException ex) 102 { 103 // XXX Should we do something else? 104 e = EmptyEnumeration.getInstance(); 105 } 106 while (e.hasMoreElements()) 107 { 108 URL url = (URL) e.nextElement(); 109 BufferedReader in; 110 String line; 111 try 112 { 113 in = new BufferedReader 114 (new InputStreamReader(url.openConnection().getInputStream(), 115 "UTF-8")); 116 line = in.readLine().trim(); 117 } 118 catch (IOException ignored) 119 { 120 continue; 121 } 122 outer: 123 while (line != null) 124 { 125 try 126 { 127 if (line.charAt(0) != '#') 128 { 129 Class<?> c = Class.forName(line); 130 descriptors.add((InputMethodDescriptor) c.newInstance()); 131 } 132 line = in.readLine().trim(); 133 } 134 catch (IOException ex) 135 { 136 continue outer; 137 } 138 catch (Exception ignored) 139 { 140 } 141 } 142 } 143 } 144 145 /** The current input method; null if no input methods are installed. */ 146 private InputMethod im; 147 148 /** Map of locales to the most recently selected input method. */ 149 private final HashMap<Locale,InputMethod> recent 150 = new HashMap<Locale,InputMethod>(); 151 152 /** The list of acceptable character subsets. */ 153 private Character.Subset[] subsets; 154 155 /** 156 * Construct an InputContext. This is protected, so clients must use 157 * {@link #getInstance()} instead. 158 */ 159 protected InputContext() 160 { 161 } 162 163 /** 164 * Returns a new InputContext. 165 * 166 * @return a new instance, initialized to the default locale if available 167 */ 168 public static InputContext getInstance() 169 { 170 InputContext ic = new InputContext(); 171 ic.selectInputMethod(Locale.getDefault()); 172 return ic; 173 } 174 175 /** 176 * Attempts to select an input method or keyboard layout which supports the 177 * given locale. This returns true if a locale is available and was selected. 178 * The following steps are taken in choosing an input method:<ul> 179 * <li>If the currently selected input method or keyboard layout supports 180 * the requested locale, it remains selected.</li> 181 * <li>If there is no input method or keyboard layout available that 182 * supports the requested locale, the current input method or keyboard 183 * layout remains selected.</li> 184 * <li>If the user has previously selected an input method or keyboard 185 * layout for the requested locale from the user interface, then the most 186 * recently selected such input method or keyboard layout is reselected.</li> 187 * <li>Otherwise, an input method or keyboard layout that supports the 188 * requested locale is selected in an implementation dependent way. This 189 * implementation chooses the first input method which supports the requested 190 * locale based on the InputMethodDescriptors loaded from the extensions 191 * installed on the CLASSPATH.</li> 192 * </ul> 193 * 194 * <p>Before switching away from an input method, any currently uncommitted 195 * text is committed. Not all host operating systems provide API to 196 * determine the locale of the currently selected native input method or 197 * keyboard layout, and to select a native input method or keyboard layout 198 * by locale. For host operating systems that don't provide such API, 199 * selectInputMethod assumes that native input methods or keyboard layouts 200 * provided by the host operating system support only the system's default 201 * locale. 202 * 203 * <p>An example of where this may be called is in a multi-language document, 204 * when moving the insertion point between sections of different locale, so 205 * that the user may use the input method appropriate to that section of the 206 * document. 207 * 208 * @param locale the desired new locale 209 * @return true if the new locale is active 210 * @throws NullPointerException if locale is null 211 */ 212 public boolean selectInputMethod(Locale locale) 213 { 214 if (im != null && im.setLocale(locale)) 215 { 216 recent.put(locale, im); 217 return true; 218 } 219 InputMethod next = recent.get(locale); 220 if (next != null) 221 for (int i = 0, limit = descriptors.size(); i < limit; i++) 222 { 223 InputMethodDescriptor d = descriptors.get(i); 224 Locale[] list; 225 try 226 { 227 list = d.getAvailableLocales(); 228 } 229 catch (AWTException ignored) 230 { 231 continue; 232 } 233 for (int j = list.length; --j >= 0; ) 234 if (locale.equals(list[j])) 235 { 236 try 237 { 238 next = d.createInputMethod(); 239 recent.put(locale, next); 240 } 241 catch (Exception ignored) 242 { 243 continue; 244 } 245 } 246 } 247 if (next == null) 248 return false; 249 // XXX I'm not sure if this does all the necessary steps in the switch. 250 if (im != null) 251 { 252 try 253 { 254 next.setCompositionEnabled(im.isCompositionEnabled()); 255 } 256 catch (UnsupportedOperationException ignored) 257 { 258 } 259 im.endComposition(); 260 im.deactivate(false); 261 im.hideWindows(); 262 } 263 im = next; 264 im.setLocale(locale); 265 im.setCharacterSubsets(subsets); 266 return true; 267 } 268 269 /** 270 * Returns the current locale of the current input method or keyboard 271 * layout. Returns null if the input context does not have a current input 272 * method or keyboard layout or if the current input method's 273 * {@link InputMethod#getLocale()} method returns null. Not all host 274 * operating systems provide API to determine the locale of the currently 275 * selected native input method or keyboard layout. For host operating 276 * systems that don't provide such API, getLocale assumes that the current 277 * locale of all native input methods or keyboard layouts provided by the 278 * host operating system is the system's default locale. 279 * 280 * @return the locale of the current input method, or null 281 * @since 1.3 282 */ 283 public Locale getLocale() 284 { 285 return im == null ? null : im.getLocale(); 286 } 287 288 /** 289 * Sets the subsets of Unicode characters allowed to be input by the current 290 * input method, as well as subsequent input methods. The value of null 291 * implies all characters are legal. Applications should not rely on this 292 * behavior, since native host input methods may not allow restrictions. 293 * If no current input method is available, this has no immediate effect. 294 * 295 * @param subsets the set of Unicode subsets to accept, or null 296 */ 297 public void setCharacterSubsets(Character.Subset[] subsets) 298 { 299 this.subsets = subsets; 300 if (im != null) 301 im.setCharacterSubsets(subsets); 302 } 303 304 /** 305 * Changes the enabled status of the current input method. An input method 306 * that is enabled for composition interprets incoming events for both 307 * composition and control purposes, while a disabled input method only 308 * interprets control commands (including commands to enable itself). 309 * 310 * @param enable whether to enable the input method 311 * @throws UnsupportedOperationException if there is no current input method, 312 * or the input method does not support enabling 313 * @see #isCompositionEnabled() 314 * @since 1.3 315 */ 316 public void setCompositionEnabled(boolean enable) 317 { 318 if (im == null) 319 throw new UnsupportedOperationException(); 320 im.setCompositionEnabled(enable); 321 } 322 323 /** 324 * Find out if the current input method is enabled. 325 * 326 * @return true if the current input method is enabled 327 * @throws UnsupportedOperationException if there is no current input method, 328 * or the input method does not support enabling 329 * @see #setCompositionEnabled(boolean) 330 * @since 1.3 331 */ 332 public boolean isCompositionEnabled() 333 { 334 if (im == null) 335 throw new UnsupportedOperationException(); 336 return im.isCompositionEnabled(); 337 } 338 339 /** 340 * Starts a reconversion operation in the current input method. The input 341 * method gets the text to reconvert from the client component, using 342 * {@link InputMethodRequests#getSelectedText(Attribute[])}. Then the 343 * composed and committed text produced by the operation is sent back to 344 * the client using a sequence of InputMethodRequests. 345 * 346 * @throws UnsupportedOperationException if there is no current input method, 347 * or the input method does not support reconversion 348 * @since 1.3 349 */ 350 public void reconvert() 351 { 352 if (im == null) 353 throw new UnsupportedOperationException(); 354 im.reconvert(); 355 } 356 357 /** 358 * Dispatches an event to the current input method. This is called 359 * automatically by AWT. If no input method is available, then the event 360 * will never be consumed. 361 * 362 * @param event the event to dispatch 363 * @throws NullPointerException if event is null 364 */ 365 public void dispatchEvent(AWTEvent event) 366 { 367 if (im != null) 368 im.dispatchEvent(event); 369 } 370 371 /** 372 * Notifies the input context that a client component has been removed from 373 * its containment hierarchy, or that input method support has been disabled 374 * for the component. This method is usually called from the client 375 * component's {@link Component#removeNotify()} method. Potentially pending 376 * input from input methods for this component is discarded. If no input 377 * methods are available, then this method has no effect. 378 * 379 * @param client the client component 380 * @throws NullPointerException if client is null 381 */ 382 public void removeNotify(Component client) 383 { 384 // XXX What to do with client information? 385 if (im != null) 386 { 387 im.deactivate(false); 388 im.removeNotify(); 389 } 390 } 391 392 /** 393 * Ends any input composition that may currently be going on in this 394 * context. Depending on the platform and possibly user preferences, this 395 * may commit or delete uncommitted text. Any changes to the text are 396 * communicated to the active component using an input method event. If no 397 * input methods are available, then this method has no effect. This may 398 * be called for a variety of reasons, such as when the user moves the 399 * insertion point in the client text outside the range of the composed text, 400 * or when text is saved to file. 401 */ 402 public void endComposition() 403 { 404 if (im != null) 405 im.endComposition(); 406 } 407 408 /** 409 * Disposes of the input context and release the resources used by it. 410 * Called automatically by AWT for the default input context of each 411 * Window. If no input methods are available, then this method has no 412 * effect. 413 */ 414 public void dispose() 415 { 416 if (im != null) 417 { 418 im.deactivate(false); 419 im.dispose(); 420 } 421 } 422 423 /** 424 * Returns a control object from the current input method, or null. A 425 * control object provides implementation-dependent methods that control 426 * the behavior of the input method or obtain information from the input 427 * method. Clients have to compare the result against known input method 428 * control object types. If no input methods are available or the current 429 * input method does not provide an input method control object, then null 430 * is returned. 431 * 432 * @return the control object, or null 433 */ 434 public Object getInputMethodControlObject() 435 { 436 return im == null ? null : im.getControlObject(); 437 } 438} // class InputContext