1 /*
   2  * Copyright (c) 1997, 2014, 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;
  27 
  28 import java.awt.Component;
  29 import java.util.Locale;
  30 import java.awt.AWTEvent;
  31 import java.beans.Transient;
  32 import java.lang.Character.Subset;
  33 import sun.awt.im.InputMethodContext;
  34 
  35 /**
  36  * Provides methods to control text input facilities such as input
  37  * methods and keyboard layouts.
  38  * Two methods handle both input methods and keyboard layouts: selectInputMethod
  39  * lets a client component select an input method or keyboard layout by locale,
  40  * getLocale lets a client component obtain the locale of the current input method
  41  * or keyboard layout.
  42  * The other methods more specifically support interaction with input methods:
  43  * They let client components control the behavior of input methods, and
  44  * dispatch events from the client component to the input method.
  45  *
  46  * <p>
  47  * By default, one InputContext instance is created per Window instance,
  48  * and this input context is shared by all components within the window's
  49  * container hierarchy. However, this means that only one text input
  50  * operation is possible at any one time within a window, and that the
  51  * text needs to be committed when moving the focus from one text component
  52  * to another. If this is not desired, text components can create their
  53  * own input context instances.
  54  *
  55  * <p>
  56  * The Java Platform supports input methods that have been developed in the Java
  57  * programming language, using the interfaces in the {@link java.awt.im.spi} package,
  58  * and installed into a Java SE Runtime Environment as extensions. Implementations
  59  * may also support using the native input methods of the platforms they run on;
  60  * however, not all platforms and locales provide input methods. Keyboard layouts
  61  * are provided by the host platform.
  62  *
  63  * <p>
  64  * Input methods are <em>unavailable</em> if (a) no input method written
  65  * in the Java programming language has been installed and (b) the Java Platform implementation
  66  * or the underlying platform does not support native input methods. In this case,
  67  * input contexts can still be created and used; their behavior is specified with
  68  * the individual methods below.
  69  *
  70  * @see java.awt.Component#getInputContext
  71  * @see java.awt.Component#enableInputMethods
  72  * @author JavaSoft Asia/Pacific
  73  * @since 1.2
  74  */
  75 
  76 public class InputContext {
  77 
  78     /**
  79      * Constructs an InputContext.
  80      * This method is protected so clients cannot instantiate
  81      * InputContext directly. Input contexts are obtained by
  82      * calling {@link #getInstance}.
  83      */
  84     protected InputContext() {
  85         // real implementation is in sun.awt.im.InputContext
  86     }
  87 
  88     /**
  89      * Returns a new InputContext instance.
  90      * @return a new InputContext instance
  91      */
  92     public static InputContext getInstance() {
  93         return new sun.awt.im.InputMethodContext();
  94     }
  95 
  96     /**
  97      * Attempts to select an input method or keyboard layout that
  98      * supports the given locale, and returns a value indicating whether such
  99      * an input method or keyboard layout has been successfully selected. The
 100      * following steps are taken until an input method has been selected:
 101      *
 102      * <ul>
 103      * <li>
 104      * If the currently selected input method or keyboard layout supports the
 105      * requested locale, it remains selected.</li>
 106      *
 107      * <li>
 108      * If there is no input method or keyboard layout available that supports
 109      * the requested locale, the current input method or keyboard layout remains
 110      * selected.</li>
 111      *
 112      * <li>
 113      * If the user has previously selected an input method or keyboard layout
 114      * for the requested locale from the user interface, then the most recently
 115      * selected such input method or keyboard layout is reselected.</li>
 116      *
 117      * <li>
 118      * Otherwise, an input method or keyboard layout that supports the requested
 119      * locale is selected in an implementation dependent way.</li>
 120      *
 121      * </ul>
 122      * Before switching away from an input method, any currently uncommitted text
 123      * is committed. If no input method or keyboard layout supporting the requested
 124      * locale is available, then false is returned.
 125      *
 126      * <p>
 127      * Not all host operating systems provide API to determine the locale of
 128      * the currently selected native input method or keyboard layout, and to
 129      * select a native input method or keyboard layout by locale.
 130      * For host operating systems that don't provide such API,
 131      * <code>selectInputMethod</code> assumes that native input methods or
 132      * keyboard layouts provided by the host operating system support only the
 133      * system's default locale.
 134      *
 135      * <p>
 136      * A text editing component may call this method, for example, when
 137      * the user changes the insertion point, so that the user can
 138      * immediately continue typing in the language of the surrounding text.
 139      *
 140      * @param locale The desired new locale.
 141      * @return true if the input method or keyboard layout that's active after
 142      *         this call supports the desired locale.
 143      * @exception NullPointerException if <code>locale</code> is null
 144      */
 145     public boolean selectInputMethod(Locale locale) {
 146         // real implementation is in sun.awt.im.InputContext
 147         return false;
 148     }
 149 
 150     /**
 151      * Returns the current locale of the current input method or keyboard
 152      * layout.
 153      * Returns null if the input context does not have a current input method
 154      * or keyboard layout or if the current input method's
 155      * {@link java.awt.im.spi.InputMethod#getLocale()} method returns null.
 156      *
 157      * <p>
 158      * Not all host operating systems provide API to determine the locale of
 159      * the currently selected native input method or keyboard layout.
 160      * For host operating systems that don't provide such API,
 161      * <code>getLocale</code> assumes that the current locale of all native
 162      * input methods or keyboard layouts provided by the host operating system
 163      * is the system's default locale.
 164      *
 165      * @return the current locale of the current input method or keyboard layout
 166      * @since 1.3
 167      */
 168     public Locale getLocale() {
 169         // real implementation is in sun.awt.im.InputContext
 170         return null;
 171     }
 172 
 173     /**
 174      * Sets the subsets of the Unicode character set that input methods of this input
 175      * context should be allowed to input. Null may be passed in to
 176      * indicate that all characters are allowed. The initial value
 177      * is null. The setting applies to the current input method as well
 178      * as input methods selected after this call is made. However,
 179      * applications cannot rely on this call having the desired effect,
 180      * since this setting cannot be passed on to all host input methods -
 181      * applications still need to apply their own character validation.
 182      * If no input methods are available, then this method has no effect.
 183      *
 184      * @param subsets The subsets of the Unicode character set from which characters may be input
 185      */
 186     public void setCharacterSubsets(Subset[] subsets) {
 187         // real implementation is in sun.awt.im.InputContext
 188     }
 189 
 190     /**
 191      * Enables or disables the current input method for composition,
 192      * depending on the value of the parameter <code>enable</code>.
 193      * <p>
 194      * An input method that is enabled for composition interprets incoming
 195      * events for both composition and control purposes, while a
 196      * disabled input method does not interpret events for composition.
 197      * Note however that events are passed on to the input method regardless
 198      * whether it is enabled or not, and that an input method that is disabled
 199      * for composition may still interpret events for control purposes,
 200      * including to enable or disable itself for composition.
 201      * <p>
 202      * For input methods provided by host operating systems, it is not always possible to
 203      * determine whether this operation is supported. For example, an input method may enable
 204      * composition only for some locales, and do nothing for other locales. For such input
 205      * methods, it is possible that this method does not throw
 206      * {@link java.lang.UnsupportedOperationException UnsupportedOperationException},
 207      * but also does not affect whether composition is enabled.
 208      *
 209      * @param enable whether to enable the current input method for composition
 210      * @throws UnsupportedOperationException if there is no current input
 211      * method available or the current input method does not support
 212      * the enabling/disabling operation
 213      * @see #isCompositionEnabled
 214      * @since 1.3
 215      */
 216     public void setCompositionEnabled(boolean enable) {
 217         // real implementation is in sun.awt.im.InputContext
 218     }
 219 
 220     /**
 221      * Determines whether the current input method is enabled for composition.
 222      * An input method that is enabled for composition interprets incoming
 223      * events for both composition and control purposes, while a
 224      * disabled input method does not interpret events for composition.
 225      *
 226      * @return <code>true</code> if the current input method is enabled for
 227      * composition; <code>false</code> otherwise
 228      * @throws UnsupportedOperationException if there is no current input
 229      * method available or the current input method does not support
 230      * checking whether it is enabled for composition
 231      * @see #setCompositionEnabled
 232      * @since 1.3
 233      */
 234     @Transient
 235     public boolean isCompositionEnabled() {
 236         // real implementation is in sun.awt.im.InputContext
 237         return false;
 238     }
 239 
 240     /**
 241      * Asks the current input method to reconvert text from the
 242      * current client component. The input method obtains the text to
 243      * be reconverted from the client component using the
 244      * {@link InputMethodRequests#getSelectedText InputMethodRequests.getSelectedText}
 245      * method. The other <code>InputMethodRequests</code> methods
 246      * must be prepared to deal with further information requests by
 247      * the input method. The composed and/or committed text will be
 248      * sent to the client component as a sequence of
 249      * <code>InputMethodEvent</code>s. If the input method cannot
 250      * reconvert the given text, the text is returned as committed
 251      * text in an <code>InputMethodEvent</code>.
 252      *
 253      * @throws UnsupportedOperationException if there is no current input
 254      * method available or the current input method does not support
 255      * the reconversion operation.
 256      *
 257      * @since 1.3
 258      */
 259     public void reconvert() {
 260         // real implementation is in sun.awt.im.InputContext
 261     }
 262 
 263     /**
 264      * Dispatches an event to the active input method. Called by AWT.
 265      * If no input method is available, then the event will never be consumed.
 266      *
 267      * @param event The event
 268      * @exception NullPointerException if <code>event</code> is null
 269      */
 270     public void dispatchEvent(AWTEvent event) {
 271         // real implementation is in sun.awt.im.InputContext
 272     }
 273 
 274     /**
 275      * Notifies the input context that a client component has been
 276      * removed from its containment hierarchy, or that input method
 277      * support has been disabled for the component. This method is
 278      * usually called from the client component's
 279      * {@link java.awt.Component#removeNotify() Component.removeNotify}
 280      * method. Potentially pending input from input methods
 281      * for this component is discarded.
 282      * If no input methods are available, then this method has no effect.
 283      *
 284      * @param client Client component
 285      * @exception NullPointerException if <code>client</code> is null
 286      */
 287     public void removeNotify(Component client) {
 288         // real implementation is in sun.awt.im.InputContext
 289     }
 290 
 291     /**
 292      * Ends any input composition that may currently be going on in this
 293      * context. Depending on the platform and possibly user preferences,
 294      * this may commit or delete uncommitted text. Any changes to the text
 295      * are communicated to the active component using an input method event.
 296      * If no input methods are available, then this method has no effect.
 297      *
 298      * <p>
 299      * A text editing component may call this in a variety of situations,
 300      * for example, when the user moves the insertion point within the text
 301      * (but outside the composed text), or when the component's text is
 302      * saved to a file or copied to the clipboard.
 303      *
 304      */
 305     public void endComposition() {
 306         // real implementation is in sun.awt.im.InputContext
 307     }
 308 
 309     /**
 310      * Releases the resources used by this input context.
 311      * Called by AWT for the default input context of each Window.
 312      * If no input methods are available, then this method
 313      * has no effect.
 314      */
 315     public void dispose() {
 316         // real implementation is in sun.awt.im.InputContext
 317     }
 318 
 319     /**
 320      * Returns a control object from the current input method, or null. A
 321      * control object provides methods that control the behavior of the
 322      * input method or obtain information from the input method. The type
 323      * of the object is an input method specific class. Clients have to
 324      * compare the result against known input method control object
 325      * classes and cast to the appropriate class to invoke the methods
 326      * provided.
 327      * <p>
 328      * If no input methods are available or the current input method does
 329      * not provide an input method control object, then null is returned.
 330      *
 331      * @return A control object from the current input method, or null.
 332      */
 333     public Object getInputMethodControlObject() {
 334         // real implementation is in sun.awt.im.InputContext
 335         return null;
 336     }
 337 
 338 }