001 /*
002 * Copyright 1997-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.im;
027
028 import java.awt.font.TextAttribute;
029 import java.util.Map;
030
031 /**
032 * An InputMethodHighlight is used to describe the highlight
033 * attributes of text being composed.
034 * The description can be at two levels:
035 * at the abstract level it specifies the conversion state and whether the
036 * text is selected; at the concrete level it specifies style attributes used
037 * to render the highlight.
038 * An InputMethodHighlight must provide the description at the
039 * abstract level; it may or may not provide the description at the concrete
040 * level.
041 * If no concrete style is provided, a renderer should use
042 * {@link java.awt.Toolkit#mapInputMethodHighlight} to map to a concrete style.
043 * <p>
044 * The abstract description consists of three fields: <code>selected</code>,
045 * <code>state</code>, and <code>variation</code>.
046 * <code>selected</code> indicates whether the text range is the one that the
047 * input method is currently working on, for example, the segment for which
048 * conversion candidates are currently shown in a menu.
049 * <code>state</code> represents the conversion state. State values are defined
050 * by the input method framework and should be distinguished in all
051 * mappings from abstract to concrete styles. Currently defined state values
052 * are raw (unconverted) and converted.
053 * These state values are recommended for use before and after the
054 * main conversion step of text composition, say, before and after kana->kanji
055 * or pinyin->hanzi conversion.
056 * The <code>variation</code> field allows input methods to express additional
057 * information about the conversion results.
058 * <p>
059 *
060 * InputMethodHighlight instances are typically used as attribute values
061 * returned from AttributedCharacterIterator for the INPUT_METHOD_HIGHLIGHT
062 * attribute. They may be wrapped into {@link java.text.Annotation Annotation}
063 * instances to indicate separate text segments.
064 *
065 * @version 1.28, 05/05/07
066 * @see java.text.AttributedCharacterIterator
067 * @since 1.2
068 */
069
070 public class InputMethodHighlight {
071
072 /**
073 * Constant for the raw text state.
074 */
075 public final static int RAW_TEXT = 0;
076
077 /**
078 * Constant for the converted text state.
079 */
080 public final static int CONVERTED_TEXT = 1;
081
082 /**
083 * Constant for the default highlight for unselected raw text.
084 */
085 public final static InputMethodHighlight UNSELECTED_RAW_TEXT_HIGHLIGHT = new InputMethodHighlight(
086 false, RAW_TEXT);
087
088 /**
089 * Constant for the default highlight for selected raw text.
090 */
091 public final static InputMethodHighlight SELECTED_RAW_TEXT_HIGHLIGHT = new InputMethodHighlight(
092 true, RAW_TEXT);
093
094 /**
095 * Constant for the default highlight for unselected converted text.
096 */
097 public final static InputMethodHighlight UNSELECTED_CONVERTED_TEXT_HIGHLIGHT = new InputMethodHighlight(
098 false, CONVERTED_TEXT);
099
100 /**
101 * Constant for the default highlight for selected converted text.
102 */
103 public final static InputMethodHighlight SELECTED_CONVERTED_TEXT_HIGHLIGHT = new InputMethodHighlight(
104 true, CONVERTED_TEXT);
105
106 /**
107 * Constructs an input method highlight record.
108 * The variation is set to 0, the style to null.
109 * @param selected Whether the text range is selected
110 * @param state The conversion state for the text range - RAW_TEXT or CONVERTED_TEXT
111 * @see InputMethodHighlight#RAW_TEXT
112 * @see InputMethodHighlight#CONVERTED_TEXT
113 * @exception IllegalArgumentException if a state other than RAW_TEXT or CONVERTED_TEXT is given
114 */
115 public InputMethodHighlight(boolean selected, int state) {
116 this (selected, state, 0, null);
117 }
118
119 /**
120 * Constructs an input method highlight record.
121 * The style is set to null.
122 * @param selected Whether the text range is selected
123 * @param state The conversion state for the text range - RAW_TEXT or CONVERTED_TEXT
124 * @param variation The style variation for the text range
125 * @see InputMethodHighlight#RAW_TEXT
126 * @see InputMethodHighlight#CONVERTED_TEXT
127 * @exception IllegalArgumentException if a state other than RAW_TEXT or CONVERTED_TEXT is given
128 */
129 public InputMethodHighlight(boolean selected, int state,
130 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,
147 int variation, Map<TextAttribute, ?> style) {
148 this .selected = selected;
149 if (!(state == RAW_TEXT || state == CONVERTED_TEXT)) {
150 throw new IllegalArgumentException(
151 "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 */
161 public boolean isSelected() {
162 return selected;
163 }
164
165 /**
166 * Returns the conversion state of the text range.
167 * @return The conversion state for the text range - RAW_TEXT or CONVERTED_TEXT.
168 * @see InputMethodHighlight#RAW_TEXT
169 * @see InputMethodHighlight#CONVERTED_TEXT
170 */
171 public int getState() {
172 return state;
173 }
174
175 /**
176 * Returns the variation of the text range.
177 */
178 public int getVariation() {
179 return variation;
180 }
181
182 /**
183 * Returns the rendering style attributes for the text range, or null.
184 * @since 1.3
185 */
186 public Map<TextAttribute, ?> getStyle() {
187 return style;
188 }
189
190 private boolean selected;
191 private int state;
192 private int variation;
193 private Map style;
194
195 };
|