KeyCodeDescriptionMapper.java revision 520a297ad1d148a57bcf6559a9802d5d49182d70 
1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.android.inputmethod.accessibility;
18
19import android.content.Context;
20import android.content.SharedPreferences;
21import android.text.TextUtils;
22
23import com.android.inputmethod.keyboard.Key;
24import com.android.inputmethod.keyboard.Keyboard;
25import com.android.inputmethod.keyboard.KeyboardId;
26import com.android.inputmethod.latin.R;
27
28import java.util.HashMap;
29
30public class KeyCodeDescriptionMapper {
31    private static KeyCodeDescriptionMapper sInstance = new KeyCodeDescriptionMapper();
32
33    // Map of key labels to spoken description resource IDs
34    private final HashMap<CharSequence, Integer> mKeyLabelMap;
35
36    // Map of key codes to spoken description resource IDs
37    private final HashMap<Integer, Integer> mKeyCodeMap;
38
39    // Map of shifted key codes to spoken description resource IDs
40    private final HashMap<Integer, Integer> mShiftedKeyCodeMap;
41
42    // Map of shift-locked key codes to spoken description resource IDs
43    private final HashMap<Integer, Integer> mShiftLockedKeyCodeMap;
44
45    public static void init(Context context, SharedPreferences prefs) {
46        sInstance.initInternal(context, prefs);
47    }
48
49    public static KeyCodeDescriptionMapper getInstance() {
50        return sInstance;
51    }
52
53    private KeyCodeDescriptionMapper() {
54        mKeyLabelMap = new HashMap<CharSequence, Integer>();
55        mKeyCodeMap = new HashMap<Integer, Integer>();
56        mShiftedKeyCodeMap = new HashMap<Integer, Integer>();
57        mShiftLockedKeyCodeMap = new HashMap<Integer, Integer>();
58    }
59
60    private void initInternal(Context context, SharedPreferences prefs) {
61        // Manual label substitutions for key labels with no string resource
62        mKeyLabelMap.put(":-)", R.string.spoken_description_smiley);
63
64        // Symbols that most TTS engines can't speak
65        mKeyCodeMap.put((int) '.', R.string.spoken_description_period);
66        mKeyCodeMap.put((int) ',', R.string.spoken_description_comma);
67        mKeyCodeMap.put((int) '(', R.string.spoken_description_left_parenthesis);
68        mKeyCodeMap.put((int) ')', R.string.spoken_description_right_parenthesis);
69        mKeyCodeMap.put((int) ':', R.string.spoken_description_colon);
70        mKeyCodeMap.put((int) ';', R.string.spoken_description_semicolon);
71        mKeyCodeMap.put((int) '!', R.string.spoken_description_exclamation_mark);
72        mKeyCodeMap.put((int) '?', R.string.spoken_description_question_mark);
73        mKeyCodeMap.put((int) '\"', R.string.spoken_description_double_quote);
74        mKeyCodeMap.put((int) '\'', R.string.spoken_description_single_quote);
75        mKeyCodeMap.put((int) '*', R.string.spoken_description_star);
76        mKeyCodeMap.put((int) '#', R.string.spoken_description_pound);
77        mKeyCodeMap.put((int) ' ', R.string.spoken_description_space);
78
79        // Non-ASCII symbols (must use escape codes!)
80        mKeyCodeMap.put((int) '\u2022', R.string.spoken_description_dot);
81        mKeyCodeMap.put((int) '\u221A', R.string.spoken_description_square_root);
82        mKeyCodeMap.put((int) '\u03C0', R.string.spoken_description_pi);
83        mKeyCodeMap.put((int) '\u0394', R.string.spoken_description_delta);
84        mKeyCodeMap.put((int) '\u2122', R.string.spoken_description_trademark);
85        mKeyCodeMap.put((int) '\u2105', R.string.spoken_description_care_of);
86        mKeyCodeMap.put((int) '\u2026', R.string.spoken_description_ellipsis);
87        mKeyCodeMap.put((int) '\u201E', R.string.spoken_description_low_double_quote);
88
89        // Special non-character codes defined in Keyboard
90        mKeyCodeMap.put(Keyboard.CODE_DELETE, R.string.spoken_description_delete);
91        mKeyCodeMap.put(Keyboard.CODE_ENTER, R.string.spoken_description_return);
92        mKeyCodeMap.put(Keyboard.CODE_SETTINGS, R.string.spoken_description_settings);
93        mKeyCodeMap.put(Keyboard.CODE_SHIFT, R.string.spoken_description_shift);
94        mKeyCodeMap.put(Keyboard.CODE_SHORTCUT, R.string.spoken_description_mic);
95        mKeyCodeMap.put(Keyboard.CODE_SWITCH_ALPHA_SYMBOL, R.string.spoken_description_to_symbol);
96        mKeyCodeMap.put(Keyboard.CODE_TAB, R.string.spoken_description_tab);
97
98        // Shifted versions of non-character codes defined in Keyboard
99        mShiftedKeyCodeMap.put(Keyboard.CODE_SHIFT, R.string.spoken_description_shift_shifted);
100
101        // Shift-locked versions of non-character codes defined in Keyboard
102        mShiftLockedKeyCodeMap.put(Keyboard.CODE_SHIFT, R.string.spoken_description_caps_lock);
103    }
104
105    /**
106     * Returns the localized description of the action performed by a specified
107     * key based on the current keyboard state.
108     * <p>
109     * The order of precedence for key descriptions is:
110     * <ol>
111     * <li>Manually-defined based on the key label</li>
112     * <li>Automatic or manually-defined based on the key code</li>
113     * <li>Automatically based on the key label</li>
114     * <li>{code null} for keys with no label or key code defined</li>
115     * </p>
116     *
117     * @param context The package's context.
118     * @param keyboard The keyboard on which the key resides.
119     * @param key The key from which to obtain a description.
120     * @return a character sequence describing the action performed by pressing
121     *         the key
122     */
123    public CharSequence getDescriptionForKey(Context context, Keyboard keyboard, Key key) {
124        if (key.mCode == Keyboard.CODE_SWITCH_ALPHA_SYMBOL) {
125            final CharSequence description = getDescriptionForSwitchAlphaSymbol(context, keyboard);
126            if (description != null)
127                return description;
128        }
129
130        if (!TextUtils.isEmpty(key.mLabel)) {
131            final String label = key.mLabel.toString().trim();
132
133            if (mKeyLabelMap.containsKey(label)) {
134                return context.getString(mKeyLabelMap.get(label));
135            } else if (label.length() == 1
136                    || (keyboard.isManualTemporaryUpperCase() && !TextUtils
137                            .isEmpty(key.mHintLabel))) {
138                return getDescriptionForKeyCode(context, keyboard, key);
139            } else {
140                return label;
141            }
142        } else if (key.mCode != Keyboard.CODE_DUMMY) {
143            return getDescriptionForKeyCode(context, keyboard, key);
144        }
145
146        return null;
147    }
148
149    /**
150     * Returns a context-specific description for the CODE_SWITCH_ALPHA_SYMBOL
151     * key or {@code null} if there is not a description provided for the
152     * current keyboard context.
153     *
154     * @param context The package's context.
155     * @param keyboard The keyboard on which the key resides.
156     * @return a character sequence describing the action performed by pressing
157     *         the key
158     */
159    private CharSequence getDescriptionForSwitchAlphaSymbol(Context context, Keyboard keyboard) {
160        final KeyboardId id = keyboard.mId;
161
162        if (id.isAlphabetKeyboard()) {
163            return context.getString(R.string.spoken_description_to_symbol);
164        } else if (id.isSymbolsKeyboard()) {
165            return context.getString(R.string.spoken_description_to_alpha);
166        } else if (id.isPhoneSymbolsKeyboard()) {
167            return context.getString(R.string.spoken_description_to_numeric);
168        } else if (id.isPhoneKeyboard()) {
169            return context.getString(R.string.spoken_description_to_symbol);
170        } else {
171            return null;
172        }
173    }
174
175    /**
176     * Returns the keycode for the specified key given the current keyboard
177     * state.
178     *
179     * @param keyboard The keyboard on which the key resides.
180     * @param key The key from which to obtain a key code.
181     * @return the key code for the specified key
182     */
183    private int getCorrectKeyCode(Keyboard keyboard, Key key) {
184        if (keyboard.isManualTemporaryUpperCase() && !TextUtils.isEmpty(key.mHintLabel)) {
185            return key.mHintLabel.charAt(0);
186        } else {
187            return key.mCode;
188        }
189    }
190
191    /**
192     * Returns a localized character sequence describing what will happen when
193     * the specified key is pressed based on its key code.
194     * <p>
195     * The order of precedence for key code descriptions is:
196     * <ol>
197     * <li>Manually-defined shift-locked description</li>
198     * <li>Manually-defined shifted description</li>
199     * <li>Manually-defined normal description</li>
200     * <li>Automatic based on the character represented by the key code</li>
201     * <li>Fall-back for undefined or control characters</li>
202     * </ol>
203     * </p>
204     *
205     * @param context The package's context.
206     * @param keyboard The keyboard on which the key resides.
207     * @param key The key from which to obtain a description.
208     * @return a character sequence describing the action performed by pressing
209     *         the key
210     */
211    private CharSequence getDescriptionForKeyCode(Context context, Keyboard keyboard, Key key) {
212        final int code = getCorrectKeyCode(keyboard, key);
213
214        if (keyboard.isShiftLocked() && mShiftLockedKeyCodeMap.containsKey(code)) {
215            return context.getString(mShiftLockedKeyCodeMap.get(code));
216        } else if (keyboard.isShiftedOrShiftLocked() && mShiftedKeyCodeMap.containsKey(code)) {
217            return context.getString(mShiftedKeyCodeMap.get(code));
218        } else if (mKeyCodeMap.containsKey(code)) {
219            return context.getString(mKeyCodeMap.get(code));
220        } else if (Character.isDefined(code) && !Character.isISOControl(code)) {
221            return Character.toString((char) code);
222        } else {
223            return context.getString(R.string.spoken_description_unknown, code);
224        }
225    }
226}
227