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 */
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</code> 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 * </code> returns <code>true</code>
97 */
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</code> 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 * </code> returns <code>true</code>
129 *
130 * @since 1.4
131 */
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 */
147 public void enableClientWindowNotification(InputMethod inputMethod, boolean enable);
148 }