001    /* InputContext.java -- provides the context for text input
002       Copyright (C) 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.awt.im;
040    
041    import gnu.java.util.EmptyEnumeration;
042    
043    import java.awt.AWTEvent;
044    import java.awt.AWTException;
045    import java.awt.Component;
046    import java.awt.im.spi.InputMethod;
047    import java.awt.im.spi.InputMethodDescriptor;
048    import java.io.BufferedReader;
049    import java.io.IOException;
050    import java.io.InputStreamReader;
051    import java.net.URL;
052    import java.text.AttributedCharacterIterator.Attribute;
053    import java.util.ArrayList;
054    import java.util.Enumeration;
055    import java.util.HashMap;
056    import 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     */
085    public 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 = (InputMethod) recent.get(locale);
220      outer:
221        if (next != null)
222          for (int i = 0, limit = descriptors.size(); i < limit; i++)
223            {
224              InputMethodDescriptor d = (InputMethodDescriptor) descriptors.get(i);
225              Locale[] list;
226              try
227                {
228                  list = d.getAvailableLocales();
229                }
230              catch (AWTException ignored)
231                {
232                  continue;
233                }
234              for (int j = list.length; --j >= 0; )
235                if (locale.equals(list[j]))
236                  {
237                    try
238                      {
239                        next = d.createInputMethod();
240                        recent.put(locale, next);
241                      }
242                    catch (Exception ignored)
243                      {
244                        continue;
245                      }
246                  }
247            }
248        if (next == null)
249          return false;
250        // XXX I'm not sure if this does all the necessary steps in the switch.
251        if (im != null)
252          {
253            try
254              {
255                next.setCompositionEnabled(im.isCompositionEnabled());
256              }
257            catch (UnsupportedOperationException ignored)
258              {
259              }
260            im.endComposition();
261            im.deactivate(false);
262            im.hideWindows();
263          }
264        im = next;
265        im.setLocale(locale);
266        im.setCharacterSubsets(subsets);
267        return true;
268      }
269    
270      /**
271       * Returns the current locale of the current input method or keyboard
272       * layout. Returns null if the input context does not have a current input
273       * method or keyboard layout or if the current input method's
274       * {@link InputMethod#getLocale()} method returns null. Not all host
275       * operating systems provide API to determine the locale of the currently
276       * selected native input method or keyboard layout. For host operating
277       * systems that don't provide such API, getLocale assumes that the current
278       * locale of all native input methods or keyboard layouts provided by the
279       * host operating system is the system's default locale.
280       *
281       * @return the locale of the current input method, or null
282       * @since 1.3
283       */
284      public Locale getLocale()
285      {
286        return im == null ? null : im.getLocale();
287      }
288    
289      /**
290       * Sets the subsets of Unicode characters allowed to be input by the current
291       * input method, as well as subsequent input methods. The value of null
292       * implies all characters are legal. Applications should not rely on this
293       * behavior, since native host input methods may not allow restrictions.
294       * If no current input method is available, this has no immediate effect.
295       *
296       * @param subsets the set of Unicode subsets to accept, or null
297       */
298      public void setCharacterSubsets(Character.Subset[] subsets)
299      {
300        this.subsets = subsets;
301        if (im != null)
302          im.setCharacterSubsets(subsets);
303      }
304    
305      /**
306       * Changes the enabled status of the current input method. An input method
307       * that is enabled for composition interprets incoming events for both
308       * composition and control purposes, while a disabled input method only
309       * interprets control commands (including commands to enable itself).
310       *
311       * @param enable whether to enable the input method
312       * @throws UnsupportedOperationException if there is no current input method,
313       *         or the input method does not support enabling
314       * @see #isCompositionEnabled()
315       * @since 1.3
316       */
317      public void setCompositionEnabled(boolean enable)
318      {
319        if (im == null)
320          throw new UnsupportedOperationException();
321        im.setCompositionEnabled(enable);
322      }
323    
324      /**
325       * Find out if the current input method is enabled.
326       *
327       * @return true if the current input method is enabled
328       * @throws UnsupportedOperationException if there is no current input method,
329       *         or the input method does not support enabling
330       * @see #setCompositionEnabled(boolean)
331       * @since 1.3
332       */
333      public boolean isCompositionEnabled()
334      {
335        if (im == null)
336          throw new UnsupportedOperationException();
337        return im.isCompositionEnabled();
338      }
339    
340      /**
341       * Starts a reconversion operation in the current input method. The input
342       * method gets the text to reconvert from the client component, using
343       * {@link InputMethodRequests#getSelectedText(Attribute[])}. Then the
344       * composed and committed text produced by the operation is sent back to
345       * the client using a sequence of InputMethodRequests.
346       *
347       * @throws UnsupportedOperationException if there is no current input method,
348       *         or the input method does not support reconversion
349       * @since 1.3
350       */
351      public void reconvert()
352      {
353        if (im == null)
354          throw new UnsupportedOperationException();
355        im.reconvert();
356      }
357    
358      /**
359       * Dispatches an event to the current input method. This is called
360       * automatically by AWT. If no input method is available, then the event
361       * will never be consumed.
362       *
363       * @param event the event to dispatch
364       * @throws NullPointerException if event is null
365       */
366      public void dispatchEvent(AWTEvent event)
367      {
368        if (im != null)
369          im.dispatchEvent(event);
370      }
371    
372      /**
373       * Notifies the input context that a client component has been removed from
374       * its containment hierarchy, or that input method support has been disabled
375       * for the component. This method is usually called from the client
376       * component's {@link Component#removeNotify()} method. Potentially pending
377       * input from input methods for this component is discarded. If no input
378       * methods are available, then this method has no effect.
379       *
380       * @param client the client component
381       * @throws NullPointerException if client is null
382       */
383      public void removeNotify(Component client)
384      {
385        // XXX What to do with client information?
386        if (im != null)
387          {
388            im.deactivate(false);
389            im.removeNotify();
390          }
391      }
392    
393      /**
394       * Ends any input composition that may currently be going on in this
395       * context. Depending on the platform and possibly user preferences, this
396       * may commit or delete uncommitted text. Any changes to the text are
397       * communicated to the active component using an input method event. If no
398       * input methods are available, then this method has no effect. This may
399       * be called for a variety of reasons, such as when the user moves the
400       * insertion point in the client text outside the range of the composed text,
401       * or when text is saved to file.
402       */
403      public void endComposition()
404      {
405        if (im != null)
406          im.endComposition();
407      }
408    
409      /**
410       * Disposes of the input context and release the resources used by it.
411       * Called automatically by AWT for the default input context of each
412       * Window. If no input methods are available, then this method has no
413       * effect.
414       */
415      public void dispose()
416      {
417        if (im != null)
418          {
419            im.deactivate(false);
420            im.dispose();
421          }
422      }
423    
424      /**
425       * Returns a control object from the current input method, or null. A
426       * control object provides implementation-dependent methods that control
427       * the behavior of the input method or obtain information from the input
428       * method. Clients have to compare the result against known input method
429       * control object types. If no input methods are available or the current
430       * input method does not provide an input method control object, then null
431       * is returned. 
432       *
433       * @return the control object, or null
434       */
435      public Object getInputMethodControlObject()
436      {
437        return im == null ? null : im.getControlObject();
438      }
439    } // class InputContext