1 /*
2  * Copyright (c) 1998, 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.spi;
27 
28 import java.awt.HeadlessException;
29 import java.awt.Window;
30 import java.awt.font.TextHitInfo;
31 import java.awt.im.InputMethodRequests;
32 import java.text.AttributedCharacterIterator;
33 import javax.swing.JFrame;
34 
35 /**
36  * Provides methods that input methods
37  * can use to communicate with their client components or to request
38  * other services.  This interface is implemented by the input method
39  * framework, and input methods call its methods on the instance they
40  * receive through
41  * {@link java.awt.im.spi.InputMethod#setInputMethodContext}.
42  * There should be no other implementors or callers.
43  *
44  * @since 1.3
45  *
46  * @author JavaSoft International
47  */
48 
49 public interface InputMethodContext extends InputMethodRequests {
50 
51     /**
52      * Creates an input method event from the arguments given
53      * and dispatches it to the client component. For arguments,
54      * see {@link java.awt.event.InputMethodEvent#InputMethodEvent}.
55      * @param id the event type
56      * @param text the combined committed and composed text
57      * @param committedCharacterCount the number of committed characters in the text
58      * @param caret the caret (a.k.a. insertion point); null if
59      * there's no caret within current composed text
60      * @param visiblePosition the position that's most important to be
61      * visible; null if there's no recommendation for a visible
62      * position within current composed text
63      */
dispatchInputMethodEvent(int id, AttributedCharacterIterator text, int committedCharacterCount, TextHitInfo caret, TextHitInfo visiblePosition)64     public void dispatchInputMethodEvent(int id,
65                 AttributedCharacterIterator text, int committedCharacterCount,
66                 TextHitInfo caret, TextHitInfo visiblePosition);
67 
68     /**
69      * Creates a top-level window for use by the input method.
70      * The intended behavior of this window is:
71      * <ul>
72      * <li>it floats above all document windows and dialogs
73      * <li>it and all components that it contains do not receive the focus
74      * <li>it has lightweight decorations, such as a reduced drag region without title
75      * </ul>
76      * However, the actual behavior with respect to these three items is platform dependent.
77      * <p>
78      * The title may or may not be displayed, depending on the actual type of window created.
79      * <p>
80      * If attachToInputContext is true, the new window will share the input context that
81      * corresponds to this input method context, so that events for components in the window
82      * are automatically dispatched to the input method.
83      * Also, when the window is opened using setVisible(true), the input context will prevent
84      * deactivate and activate calls to the input method that might otherwise be caused.
85      * <p>
86      * Input methods must call {@link java.awt.Window#dispose() Window.dispose} on the
87      * returned input method window when it is no longer needed.
88      *
89      * @param title the title to be displayed in the window's title bar,
90      *              if there is such a title bar.
91      *              A {@code null} value is treated as an empty string, "".
92      * @param attachToInputContext whether this window should share the input context
93      *              that corresponds to this input method context
94      * @return a window with special characteristics for use by input methods
95      * @exception HeadlessException if {@code GraphicsEnvironment.isHeadless}
96      *            returns {@code true}
97      */
createInputMethodWindow(String title, boolean attachToInputContext)98     public Window createInputMethodWindow(String title, boolean attachToInputContext);
99 
100     /**
101      * Creates a top-level Swing JFrame for use by the input method.
102      * The intended behavior of this window is:
103      * <ul>
104      * <li>it floats above all document windows and dialogs
105      * <li>it and all components that it contains do not receive the focus
106      * <li>it has lightweight decorations, such as a reduced drag region without title
107      * </ul>
108      * However, the actual behavior with respect to these three items is platform dependent.
109      * <p>
110      * The title may or may not be displayed, depending on the actual type of window created.
111      * <p>
112      * If attachToInputContext is true, the new window will share the input context that
113      * corresponds to this input method context, so that events for components in the window
114      * are automatically dispatched to the input method.
115      * Also, when the window is opened using setVisible(true), the input context will prevent
116      * deactivate and activate calls to the input method that might otherwise be caused.
117      * <p>
118      * Input methods must call {@link java.awt.Window#dispose() Window.dispose} on the
119      * returned input method window when it is no longer needed.
120      *
121      * @param title the title to be displayed in the window's title bar,
122      *              if there is such a title bar.
123      *              A {@code null} value is treated as an empty string, "".
124      * @param attachToInputContext whether this window should share the input context
125      *              that corresponds to this input method context
126      * @return a JFrame with special characteristics for use by input methods
127      * @exception HeadlessException if {@code GraphicsEnvironment.isHeadless}
128      *            returns {@code true}
129      *
130      * @since 1.4
131      */
createInputMethodJFrame(String title, boolean attachToInputContext)132     public JFrame createInputMethodJFrame(String title, boolean attachToInputContext);
133 
134     /**
135      * Enables or disables notification of the current client window's
136      * location and state for the specified input method. When
137      * notification is enabled, the input method's {@link
138      * java.awt.im.spi.InputMethod#notifyClientWindowChange
139      * notifyClientWindowChange} method is called as described in that
140      * method's specification. Notification is automatically disabled
141      * when the input method is disposed.
142      *
143      * @param inputMethod the input method for which notifications are
144      * enabled or disabled
145      * @param enable true to enable, false to disable
146      */
enableClientWindowNotification(InputMethod inputMethod, boolean enable)147     public void enableClientWindowNotification(InputMethod inputMethod, boolean enable);
148 }
149