Home » openjdk-7 » java » awt » im » spi » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 2004, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.awt.im.spi;
   27   
   28   import java.util.Locale;
   29   import java.awt.AWTEvent;
   30   import java.awt.Rectangle;
   31   import java.lang.Character.Subset;
   32   
   33   
   34   /**
   35    * Defines the interface for an input method that supports complex text input.
   36    * Input methods traditionally support text input for languages that have
   37    * more characters than can be represented on a standard-size keyboard,
   38    * such as Chinese, Japanese, and Korean. However, they may also be used to
   39    * support phonetic text input for English or character reordering for Thai.
   40    * <p>
   41    * Subclasses of InputMethod can be loaded by the input method framework; they
   42    * can then be selected either through the API
   43    * ({@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod})
   44    * or the user interface (the input method selection menu).
   45    *
   46    * @since 1.3
   47    *
   48    * @author JavaSoft International
   49    */
   50   
   51   public interface InputMethod {
   52   
   53       /**
   54        * Sets the input method context, which is used to dispatch input method
   55        * events to the client component and to request information from
   56        * the client component.
   57        * <p>
   58        * This method is called once immediately after instantiating this input
   59        * method.
   60        *
   61        * @param context the input method context for this input method
   62        * @exception NullPointerException if <code>context</code> is null
   63        */
   64       public void setInputMethodContext(InputMethodContext context);
   65   
   66       /**
   67        * Attempts to set the input locale. If the input method supports the
   68        * desired locale, it changes its behavior to support input for the locale
   69        * and returns true.
   70        * Otherwise, it returns false and does not change its behavior.
   71        * <p>
   72        * This method is called
   73        * <ul>
   74        * <li>by {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod},
   75        * <li>when switching to this input method through the user interface if the user
   76        *     specified a locale or if the previously selected input method's
   77        *     {@link java.awt.im.spi.InputMethod#getLocale getLocale} method
   78        *     returns a non-null value.
   79        * </ul>
   80        *
   81        * @param locale locale to input
   82        * @return whether the specified locale is supported
   83        * @exception NullPointerException if <code>locale</code> is null
   84        */
   85       public boolean setLocale(Locale locale);
   86   
   87       /**
   88        * Returns the current input locale. Might return null in exceptional cases.
   89        * <p>
   90        * This method is called
   91        * <ul>
   92        * <li>by {@link java.awt.im.InputContext#getLocale InputContext.getLocale} and
   93        * <li>when switching from this input method to a different one through the
   94        *     user interface.
   95        * </ul>
   96        *
   97        * @return the current input locale, or null
   98        */
   99       public Locale getLocale();
  100   
  101       /**
  102        * Sets the subsets of the Unicode character set that this input method
  103        * is allowed to input. Null may be passed in to indicate that all
  104        * characters are allowed.
  105        * <p>
  106        * This method is called
  107        * <ul>
  108        * <li>immediately after instantiating this input method,
  109        * <li>when switching to this input method from a different one, and
  110        * <li>by {@link java.awt.im.InputContext#setCharacterSubsets InputContext.setCharacterSubsets}.
  111        * </ul>
  112        *
  113        * @param subsets the subsets of the Unicode character set from which
  114        * characters may be input
  115        */
  116       public void setCharacterSubsets(Subset[] subsets);
  117   
  118       /**
  119        * Enables or disables this input method for composition,
  120        * depending on the value of the parameter <code>enable</code>.
  121        * <p>
  122        * An input method that is enabled for composition interprets incoming
  123        * events for both composition and control purposes, while a
  124        * disabled input method does not interpret events for composition.
  125        * Note however that events are passed on to the input method regardless
  126        * whether it is enabled or not, and that an input method that is disabled
  127        * for composition may still interpret events for control purposes,
  128        * including to enable or disable itself for composition.
  129        * <p>
  130        * For input methods provided by host operating systems, it is not always possible to
  131        * determine whether this operation is supported. For example, an input method may enable
  132        * composition only for some locales, and do nothing for other locales. For such input
  133        * methods, it is possible that this method does not throw
  134        * {@link java.lang.UnsupportedOperationException UnsupportedOperationException},
  135        * but also does not affect whether composition is enabled.
  136        * <p>
  137        * This method is called
  138        * <ul>
  139        * <li>by {@link java.awt.im.InputContext#setCompositionEnabled InputContext.setCompositionEnabled},
  140        * <li>when switching to this input method from a different one using the
  141        *     user interface or
  142        *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod},
  143        *     if the previously selected input method's
  144        *     {@link java.awt.im.spi.InputMethod#isCompositionEnabled isCompositionEnabled}
  145        *     method returns without throwing an exception.
  146        * </ul>
  147        *
  148        * @param enable whether to enable the input method for composition
  149        * @throws UnsupportedOperationException if this input method does not
  150        * support the enabling/disabling operation
  151        * @see #isCompositionEnabled
  152        */
  153       public void setCompositionEnabled(boolean enable);
  154   
  155       /**
  156        * Determines whether this input method is enabled.
  157        * An input method that is enabled for composition interprets incoming
  158        * events for both composition and control purposes, while a
  159        * disabled input method does not interpret events for composition.
  160        * <p>
  161        * This method is called
  162        * <ul>
  163        * <li>by {@link java.awt.im.InputContext#isCompositionEnabled InputContext.isCompositionEnabled} and
  164        * <li>when switching from this input method to a different one using the
  165        *     user interface or
  166        *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}.
  167        * </ul>
  168        *
  169        * @return <code>true</code> if this input method is enabled for
  170        * composition; <code>false</code> otherwise.
  171        * @throws UnsupportedOperationException if this input method does not
  172        * support checking whether it is enabled for composition
  173        * @see #setCompositionEnabled
  174        */
  175       public boolean isCompositionEnabled();
  176   
  177       /**
  178        * Starts the reconversion operation. The input method obtains the
  179        * text to be reconverted from the current client component using the
  180        * {@link java.awt.im.InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText}
  181        * method. It can use other <code>InputMethodRequests</code>
  182        * methods to request additional information required for the
  183        * reconversion operation. The composed and committed text
  184        * produced by the operation is sent to the client component as a
  185        * sequence of <code>InputMethodEvent</code>s. If the given text
  186        * cannot be reconverted, the same text should be sent to the
  187        * client component as committed text.
  188        * <p>
  189        * This method is called by
  190        * {@link java.awt.im.InputContext#reconvert() InputContext.reconvert}.
  191        *
  192        * @throws UnsupportedOperationException if the input method does not
  193        * support the reconversion operation.
  194        */
  195       public void reconvert();
  196   
  197       /**
  198        * Dispatches the event to the input method. If input method support is
  199        * enabled for the focussed component, incoming events of certain types
  200        * are dispatched to the current input method for this component before
  201        * they are dispatched to the component's methods or event listeners.
  202        * The input method decides whether it needs to handle the event. If it
  203        * does, it also calls the event's <code>consume</code> method; this
  204        * causes the event to not get dispatched to the component's event
  205        * processing methods or event listeners.
  206        * <p>
  207        * Events are dispatched if they are instances of InputEvent or its
  208        * subclasses.
  209        * This includes instances of the AWT classes KeyEvent and MouseEvent.
  210        * <p>
  211        * This method is called by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}.
  212        *
  213        * @param event the event being dispatched to the input method
  214        * @exception NullPointerException if <code>event</code> is null
  215        */
  216       public void dispatchEvent(AWTEvent event);
  217   
  218       /**
  219        * Notifies this input method of changes in the client window
  220        * location or state. This method is called while this input
  221        * method is the current input method of its input context and
  222        * notifications for it are enabled (see {@link
  223        * InputMethodContext#enableClientWindowNotification
  224        * InputMethodContext.enableClientWindowNotification}). Calls
  225        * to this method are temporarily suspended if the input context's
  226        * {@link java.awt.im.InputContext#removeNotify removeNotify}
  227        * method is called, and resume when the input method is activated
  228        * for a new client component. It is called in the following
  229        * situations:
  230        * <ul>
  231        * <li>
  232        * when the window containing the current client component changes
  233        * in location, size, visibility, iconification state, or when the
  234        * window is closed.</li>
  235        * <li>
  236        * from <code> enableClientWindowNotification(inputMethod,
  237        * true)</code> if the current client component exists,</li>
  238        * <li>
  239        * when activating the input method for the first time after it
  240        * called
  241        * <code>enableClientWindowNotification(inputMethod,
  242        * true)</code> if during the call no current client component was
  243        * available,</li>
  244        * <li>
  245        * when activating the input method for a new client component
  246        * after the input context's removeNotify method has been
  247        * called.</li>
  248        * </ul>
  249        * @param bounds client window's {@link
  250        * java.awt.Component#getBounds bounds} on the screen; or null if
  251        * the client window is iconified or invisible
  252        */
  253       public void notifyClientWindowChange(Rectangle bounds);
  254   
  255       /**
  256        * Activates the input method for immediate input processing.
  257        * <p>
  258        * If an input method provides its own windows, it should make sure
  259        * at this point that all necessary windows are open and visible.
  260        * <p>
  261        * This method is called
  262        * <ul>
  263        * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}
  264        *     when a client component receives a FOCUS_GAINED event,
  265        * <li>when switching to this input method from a different one using the
  266        *     user interface or
  267        *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}.
  268        * </ul>
  269        * The method is only called when the input method is inactive.
  270        * A newly instantiated input method is assumed to be inactive.
  271        */
  272       public void activate();
  273   
  274       /**
  275        * Deactivates the input method.
  276        * The isTemporary argument has the same meaning as in
  277        * {@link java.awt.event.FocusEvent#isTemporary FocusEvent.isTemporary}.
  278        * <p>
  279        * If an input method provides its own windows, only windows that relate
  280        * to the current composition (such as a lookup choice window) should be
  281        * closed at this point.
  282        * It is possible that the input method will be immediately activated again
  283        * for a different client component, and closing and reopening more
  284        * persistent windows (such as a control panel) would create unnecessary
  285        * screen flicker.
  286        * Before an instance of a different input method class is activated,
  287        * {@link #hideWindows} is called on the current input method.
  288        * <p>
  289        * This method is called
  290        * <ul>
  291        * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}
  292        *     when a client component receives a FOCUS_LOST event,
  293        * <li>when switching from this input method to a different one using the
  294        *     user interface or
  295        *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod},
  296        * <li>before {@link #removeNotify removeNotify} if the current client component is
  297        *     removed.
  298        * </ul>
  299        * The method is only called when the input method is active.
  300        *
  301        * @param isTemporary whether the focus change is temporary
  302        */
  303       public void deactivate(boolean isTemporary);
  304   
  305       /**
  306        * Closes or hides all windows opened by this input method instance or
  307        * its class.
  308        * <p>
  309        * This method is called
  310        * <ul>
  311        * <li>before calling {@link #activate activate} on an instance of a different input
  312        *     method class,
  313        * <li>before calling {@link #dispose dispose} on this input method.
  314        * </ul>
  315        * The method is only called when the input method is inactive.
  316        */
  317       public void hideWindows();
  318   
  319       /**
  320        * Notifies the input method that a client component has been
  321        * removed from its containment hierarchy, or that input method
  322        * support has been disabled for the component.
  323        * <p>
  324        * This method is called by {@link java.awt.im.InputContext#removeNotify InputContext.removeNotify}.
  325        * <p>
  326        * The method is only called when the input method is inactive.
  327        */
  328       public void removeNotify();
  329   
  330       /**
  331        * Ends any input composition that may currently be going on in this
  332        * context. Depending on the platform and possibly user preferences,
  333        * this may commit or delete uncommitted text. Any changes to the text
  334        * are communicated to the active component using an input method event.
  335        *
  336        * <p>
  337        * A text editing component may call this in a variety of situations,
  338        * for example, when the user moves the insertion point within the text
  339        * (but outside the composed text), or when the component's text is
  340        * saved to a file or copied to the clipboard.
  341        * <p>
  342        * This method is called
  343        * <ul>
  344        * <li>by {@link java.awt.im.InputContext#endComposition InputContext.endComposition},
  345        * <li>by {@link java.awt.im.InputContext#dispatchEvent InputContext.dispatchEvent}
  346        *     when switching to a different client component
  347        * <li>when switching from this input method to a different one using the
  348        *     user interface or
  349        *     {@link java.awt.im.InputContext#selectInputMethod InputContext.selectInputMethod}.
  350        * </ul>
  351        */
  352       public void endComposition();
  353   
  354       /**
  355        * Releases the resources used by this input method.
  356        * In particular, the input method should dispose windows and close files that are no
  357        * longer needed.
  358        * <p>
  359        * This method is called by {@link java.awt.im.InputContext#dispose InputContext.dispose}.
  360        * <p>
  361        * The method is only called when the input method is inactive.
  362        * No method of this interface is called on this instance after dispose.
  363        */
  364       public void dispose();
  365   
  366       /**
  367        * Returns a control object from this input method, or null. A
  368        * control object provides methods that control the behavior of the
  369        * input method or obtain information from the input method. The type
  370        * of the object is an input method specific class. Clients have to
  371        * compare the result against known input method control object
  372        * classes and cast to the appropriate class to invoke the methods
  373        * provided.
  374        * <p>
  375        * This method is called by
  376        * {@link java.awt.im.InputContext#getInputMethodControlObject InputContext.getInputMethodControlObject}.
  377        *
  378        * @return a control object from this input method, or null
  379        */
  380       public Object getControlObject();
  381   
  382   }

Home » openjdk-7 » java » awt » im » spi » [javadoc | source]