KeyCharacterMap.h revision 6ec6f79e1ac1714e3b837796e99f07ff88f66601 
1/*
2 * Copyright (C) 2008 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
17#ifndef _ANDROIDFW_KEY_CHARACTER_MAP_H
18#define _ANDROIDFW_KEY_CHARACTER_MAP_H
19
20#include <stdint.h>
21
22#if HAVE_ANDROID_OS
23#include <binder/IBinder.h>
24#endif
25
26#include <androidfw/Input.h>
27#include <utils/Errors.h>
28#include <utils/KeyedVector.h>
29#include <utils/Tokenizer.h>
30#include <utils/String8.h>
31#include <utils/Unicode.h>
32#include <utils/RefBase.h>
33
34namespace android {
35
36/**
37 * Describes a mapping from Android key codes to characters.
38 * Also specifies other functions of the keyboard such as the keyboard type
39 * and key modifier semantics.
40 *
41 * This object is immutable after it has been loaded.
42 */
43class KeyCharacterMap : public RefBase {
44public:
45    enum KeyboardType {
46        KEYBOARD_TYPE_UNKNOWN = 0,
47        KEYBOARD_TYPE_NUMERIC = 1,
48        KEYBOARD_TYPE_PREDICTIVE = 2,
49        KEYBOARD_TYPE_ALPHA = 3,
50        KEYBOARD_TYPE_FULL = 4,
51        KEYBOARD_TYPE_SPECIAL_FUNCTION = 5,
52        KEYBOARD_TYPE_OVERLAY = 6,
53    };
54
55    enum Format {
56        // Base keyboard layout, may contain device-specific options, such as "type" declaration.
57        FORMAT_BASE = 0,
58        // Overlay keyboard layout, more restrictive, may be published by applications,
59        // cannot override device-specific options.
60        FORMAT_OVERLAY = 1,
61        // Either base or overlay layout ok.
62        FORMAT_ANY = 2,
63    };
64
65    // Substitute key code and meta state for fallback action.
66    struct FallbackAction {
67        int32_t keyCode;
68        int32_t metaState;
69    };
70
71    /* Loads a key character map from a file. */
72    static status_t load(const String8& filename, Format format, sp<KeyCharacterMap>* outMap);
73
74    /* Loads a key character map from its string contents. */
75    static status_t loadContents(const String8& filename,
76            const char* contents, Format format, sp<KeyCharacterMap>* outMap);
77
78    /* Combines a base key character map and an overlay. */
79    static sp<KeyCharacterMap> combine(const sp<KeyCharacterMap>& base,
80            const sp<KeyCharacterMap>& overlay);
81
82    /* Returns an empty key character map. */
83    static sp<KeyCharacterMap> empty();
84
85    /* Gets the keyboard type. */
86    int32_t getKeyboardType() const;
87
88    /* Gets the primary character for this key as in the label physically printed on it.
89     * Returns 0 if none (eg. for non-printing keys). */
90    char16_t getDisplayLabel(int32_t keyCode) const;
91
92    /* Gets the Unicode character for the number or symbol generated by the key
93     * when the keyboard is used as a dialing pad.
94     * Returns 0 if no number or symbol is generated.
95     */
96    char16_t getNumber(int32_t keyCode) const;
97
98    /* Gets the Unicode character generated by the key and meta key modifiers.
99     * Returns 0 if no character is generated.
100     */
101    char16_t getCharacter(int32_t keyCode, int32_t metaState) const;
102
103    /* Gets the fallback action to use by default if the application does not
104     * handle the specified key.
105     * Returns true if an action was available, false if none.
106     */
107    bool getFallbackAction(int32_t keyCode, int32_t metaState,
108            FallbackAction* outFallbackAction) const;
109
110    /* Gets the first matching Unicode character that can be generated by the key,
111     * preferring the one with the specified meta key modifiers.
112     * Returns 0 if no matching character is generated.
113     */
114    char16_t getMatch(int32_t keyCode, const char16_t* chars,
115            size_t numChars, int32_t metaState) const;
116
117    /* Gets a sequence of key events that could plausibly generate the specified
118     * character sequence.  Returns false if some of the characters cannot be generated.
119     */
120    bool getEvents(int32_t deviceId, const char16_t* chars, size_t numChars,
121            Vector<KeyEvent>& outEvents) const;
122
123#if HAVE_ANDROID_OS
124    /* Reads a key map from a parcel. */
125    static sp<KeyCharacterMap> readFromParcel(Parcel* parcel);
126
127    /* Writes a key map to a parcel. */
128    void writeToParcel(Parcel* parcel) const;
129#endif
130
131protected:
132    virtual ~KeyCharacterMap();
133
134private:
135    struct Behavior {
136        Behavior();
137        Behavior(const Behavior& other);
138
139        /* The next behavior in the list, or NULL if none. */
140        Behavior* next;
141
142        /* The meta key modifiers for this behavior. */
143        int32_t metaState;
144
145        /* The character to insert. */
146        char16_t character;
147
148        /* The fallback keycode if the key is not handled. */
149        int32_t fallbackKeyCode;
150    };
151
152    struct Key {
153        Key();
154        Key(const Key& other);
155        ~Key();
156
157        /* The single character label printed on the key, or 0 if none. */
158        char16_t label;
159
160        /* The number or symbol character generated by the key, or 0 if none. */
161        char16_t number;
162
163        /* The list of key behaviors sorted from most specific to least specific
164         * meta key binding. */
165        Behavior* firstBehavior;
166    };
167
168    class Parser {
169        enum State {
170            STATE_TOP = 0,
171            STATE_KEY = 1,
172        };
173
174        enum {
175            PROPERTY_LABEL = 1,
176            PROPERTY_NUMBER = 2,
177            PROPERTY_META = 3,
178        };
179
180        struct Property {
181            inline Property(int32_t property = 0, int32_t metaState = 0) :
182                    property(property), metaState(metaState) { }
183
184            int32_t property;
185            int32_t metaState;
186        };
187
188        KeyCharacterMap* mMap;
189        Tokenizer* mTokenizer;
190        Format mFormat;
191        State mState;
192        int32_t mKeyCode;
193
194    public:
195        Parser(KeyCharacterMap* map, Tokenizer* tokenizer, Format format);
196        ~Parser();
197        status_t parse();
198
199    private:
200        status_t parseType();
201        status_t parseKey();
202        status_t parseKeyProperty();
203        status_t parseModifier(const String8& token, int32_t* outMetaState);
204        status_t parseCharacterLiteral(char16_t* outCharacter);
205    };
206
207    static sp<KeyCharacterMap> sEmpty;
208
209    KeyedVector<int32_t, Key*> mKeys;
210    int mType;
211
212    KeyCharacterMap();
213    KeyCharacterMap(const KeyCharacterMap& other);
214
215    bool getKey(int32_t keyCode, const Key** outKey) const;
216    bool getKeyBehavior(int32_t keyCode, int32_t metaState,
217            const Key** outKey, const Behavior** outBehavior) const;
218
219    bool findKey(char16_t ch, int32_t* outKeyCode, int32_t* outMetaState) const;
220
221    static status_t load(Tokenizer* tokenizer, Format format, sp<KeyCharacterMap>* outMap);
222
223    static void addKey(Vector<KeyEvent>& outEvents,
224            int32_t deviceId, int32_t keyCode, int32_t metaState, bool down, nsecs_t time);
225    static void addMetaKeys(Vector<KeyEvent>& outEvents,
226            int32_t deviceId, int32_t metaState, bool down, nsecs_t time,
227            int32_t* currentMetaState);
228    static bool addSingleEphemeralMetaKey(Vector<KeyEvent>& outEvents,
229            int32_t deviceId, int32_t metaState, bool down, nsecs_t time,
230            int32_t keyCode, int32_t keyMetaState,
231            int32_t* currentMetaState);
232    static void addDoubleEphemeralMetaKey(Vector<KeyEvent>& outEvents,
233            int32_t deviceId, int32_t metaState, bool down, nsecs_t time,
234            int32_t leftKeyCode, int32_t leftKeyMetaState,
235            int32_t rightKeyCode, int32_t rightKeyMetaState,
236            int32_t eitherKeyMetaState,
237            int32_t* currentMetaState);
238    static void addLockedMetaKey(Vector<KeyEvent>& outEvents,
239            int32_t deviceId, int32_t metaState, nsecs_t time,
240            int32_t keyCode, int32_t keyMetaState,
241            int32_t* currentMetaState);
242};
243
244} // namespace android
245
246#endif // _ANDROIDFW_KEY_CHARACTER_MAP_H
247