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