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.font.TextAttribute;
29 import java.util.Map;
30
31 /**
32 * An InputMethodHighlight is used to describe the highlight
33 * attributes of text being composed.
34 * The description can be at two levels:
35 * at the abstract level it specifies the conversion state and whether the
36 * text is selected; at the concrete level it specifies style attributes used
37 * to render the highlight.
38 * An InputMethodHighlight must provide the description at the
39 * abstract level; it may or may not provide the description at the concrete
40 * level.
41 * If no concrete style is provided, a renderer should use
42 * {@link java.awt.Toolkit#mapInputMethodHighlight} to map to a concrete style.
43 * <p>
44 * The abstract description consists of three fields: <code>selected</code>,
45 * <code>state</code>, and <code>variation</code>.
46 * <code>selected</code> indicates whether the text range is the one that the
47 * input method is currently working on, for example, the segment for which
48 * conversion candidates are currently shown in a menu.
49 * <code>state</code> represents the conversion state. State values are defined
50 * by the input method framework and should be distinguished in all
51 * mappings from abstract to concrete styles. Currently defined state values
52 * are raw (unconverted) and converted.
53 * These state values are recommended for use before and after the
54 * main conversion step of text composition, say, before and after kana->kanji
55 * or pinyin->hanzi conversion.
56 * The <code>variation</code> field allows input methods to express additional
57 * information about the conversion results.
58 * <p>
59 *
60 * InputMethodHighlight instances are typically used as attribute values
61 * returned from AttributedCharacterIterator for the INPUT_METHOD_HIGHLIGHT
62 * attribute. They may be wrapped into {@link java.text.Annotation Annotation}
63 * instances to indicate separate text segments.
64 *
65 * @see java.text.AttributedCharacterIterator
66 * @since 1.2
67 */
68
69 public class InputMethodHighlight {
70
71 /**
72 * Constant for the raw text state.
73 */
74 public final static int RAW_TEXT = 0;
75
76 /**
77 * Constant for the converted text state.
78 */
79 public final static int CONVERTED_TEXT = 1;
80
81
82 /**
83 * Constant for the default highlight for unselected raw text.
84 */
85 public final static InputMethodHighlight UNSELECTED_RAW_TEXT_HIGHLIGHT =
86 new InputMethodHighlight(false, RAW_TEXT);
87
88 /**
89 * Constant for the default highlight for selected raw text.
90 */
91 public final static InputMethodHighlight SELECTED_RAW_TEXT_HIGHLIGHT =
92 new InputMethodHighlight(true, RAW_TEXT);
93
94 /**
95 * Constant for the default highlight for unselected converted text.
96 */
97 public final static InputMethodHighlight UNSELECTED_CONVERTED_TEXT_HIGHLIGHT =
98 new InputMethodHighlight(false, CONVERTED_TEXT);
99
100 /**
101 * Constant for the default highlight for selected converted text.
102 */
103 public final static InputMethodHighlight SELECTED_CONVERTED_TEXT_HIGHLIGHT =
104 new InputMethodHighlight(true, CONVERTED_TEXT);
105
106
107 /**
108 * Constructs an input method highlight record.
109 * The variation is set to 0, the style to null.
110 * @param selected Whether the text range is selected
111 * @param state The conversion state for the text range - RAW_TEXT or CONVERTED_TEXT
112 * @see InputMethodHighlight#RAW_TEXT
113 * @see InputMethodHighlight#CONVERTED_TEXT
114 * @exception IllegalArgumentException if a state other than RAW_TEXT or CONVERTED_TEXT is given
115 */
116 public InputMethodHighlight(boolean selected, int state) {
117 this(selected, state, 0, null);
118 }
119
120 /**
121 * Constructs an input method highlight record.
122 * The style is set to null.
123 * @param selected Whether the text range is selected
124 * @param state The conversion state for the text range - RAW_TEXT or CONVERTED_TEXT
125 * @param variation The style variation for the text range
126 * @see InputMethodHighlight#RAW_TEXT
127 * @see InputMethodHighlight#CONVERTED_TEXT
128 * @exception IllegalArgumentException if a state other than RAW_TEXT or CONVERTED_TEXT is given
129 */
130 public InputMethodHighlight(boolean selected, int state, int variation) {
131 this(selected, state, variation, null);
132 }
133
134 /**
135 * Constructs an input method highlight record.
136 * The style attributes map provided must be unmodifiable.
137 * @param selected whether the text range is selected
138 * @param state the conversion state for the text range - RAW_TEXT or CONVERTED_TEXT
139 * @param variation the variation for the text range
140 * @param style the rendering style attributes for the text range, or null
141 * @see InputMethodHighlight#RAW_TEXT
142 * @see InputMethodHighlight#CONVERTED_TEXT
143 * @exception IllegalArgumentException if a state other than RAW_TEXT or CONVERTED_TEXT is given
144 * @since 1.3
145 */
146 public InputMethodHighlight(boolean selected, int state, int variation,
147 Map<TextAttribute,?> style)
148 {
149 this.selected = selected;
150 if (!(state == RAW_TEXT || state == CONVERTED_TEXT)) {
151 throw new IllegalArgumentException("unknown input method highlight state");
152 }
153 this.state = state;
154 this.variation = variation;
155 this.style = style;
156 }
157
158 /**
159 * Returns whether the text range is selected.
160 * @return whether the text range is selected
161 */
162 public boolean isSelected() {
163 return selected;
164 }
165
166 /**
167 * Returns the conversion state of the text range.
168 * @return The conversion state for the text range - RAW_TEXT or CONVERTED_TEXT.
169 * @see InputMethodHighlight#RAW_TEXT
170 * @see InputMethodHighlight#CONVERTED_TEXT
171 */
172 public int getState() {
173 return state;
174 }
175
176 /**
177 * Returns the variation of the text range.
178 * @return the variation of the text range
179 */
180 public int getVariation() {
181 return variation;
182 }
183
184 /**
185 * Returns the rendering style attributes for the text range, or null.
186 * @return the rendering style attributes for the text range, or null
187 * @since 1.3
188 */
189 public Map<TextAttribute,?> getStyle() {
190 return style;
191 }
192
193 private boolean selected;
194 private int state;
195 private int variation;
196 private Map<TextAttribute, ?> style;
197
198 };