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    /* Maps a scan code and usage code to a key code, in case this key map overrides
124     * the mapping in some way. */
125    status_t mapKey(int32_t scanCode, int32_t usageCode, int32_t* outKeyCode) const;
126
127#if HAVE_ANDROID_OS
128    /* Reads a key map from a parcel. */
129    static sp<KeyCharacterMap> readFromParcel(Parcel* parcel);
130
131    /* Writes a key map to a parcel. */
132    void writeToParcel(Parcel* parcel) const;
133#endif
134
135protected:
136    virtual ~KeyCharacterMap();
137
138private:
139    struct Behavior {
140        Behavior();
141        Behavior(const Behavior& other);
142
143        /* The next behavior in the list, or NULL if none. */
144        Behavior* next;
145
146        /* The meta key modifiers for this behavior. */
147        int32_t metaState;
148
149        /* The character to insert. */
150        char16_t character;
151
152        /* The fallback keycode if the key is not handled. */
153        int32_t fallbackKeyCode;
154    };
155
156    struct Key {
157        Key();
158        Key(const Key& other);
159        ~Key();
160
161        /* The single character label printed on the key, or 0 if none. */
162        char16_t label;
163
164        /* The number or symbol character generated by the key, or 0 if none. */
165        char16_t number;
166
167        /* The list of key behaviors sorted from most specific to least specific
168         * meta key binding. */
169        Behavior* firstBehavior;
170    };
171
172    class Parser {
173        enum State {
174            STATE_TOP = 0,
175            STATE_KEY = 1,
176        };
177
178        enum {
179            PROPERTY_LABEL = 1,
180            PROPERTY_NUMBER = 2,
181            PROPERTY_META = 3,
182        };
183
184        struct Property {
185            inline Property(int32_t property = 0, int32_t metaState = 0) :
186                    property(property), metaState(metaState) { }
187
188            int32_t property;
189            int32_t metaState;
190        };
191
192        KeyCharacterMap* mMap;
193        Tokenizer* mTokenizer;
194        Format mFormat;
195        State mState;
196        int32_t mKeyCode;
197
198    public:
199        Parser(KeyCharacterMap* map, Tokenizer* tokenizer, Format format);
200        ~Parser();
201        status_t parse();
202
203    private:
204        status_t parseType();
205        status_t parseMap();
206        status_t parseMapKey();
207        status_t parseKey();
208        status_t parseKeyProperty();
209        status_t finishKey(Key* key);
210        status_t parseModifier(const String8& token, int32_t* outMetaState);
211        status_t parseCharacterLiteral(char16_t* outCharacter);
212    };
213
214    static sp<KeyCharacterMap> sEmpty;
215
216    KeyedVector<int32_t, Key*> mKeys;
217    int mType;
218
219    KeyedVector<int32_t, int32_t> mKeysByScanCode;
220    KeyedVector<int32_t, int32_t> mKeysByUsageCode;
221
222    KeyCharacterMap();
223    KeyCharacterMap(const KeyCharacterMap& other);
224
225    bool getKey(int32_t keyCode, const Key** outKey) const;
226    bool getKeyBehavior(int32_t keyCode, int32_t metaState,
227            const Key** outKey, const Behavior** outBehavior) const;
228    static bool matchesMetaState(int32_t eventMetaState, int32_t behaviorMetaState);
229
230    bool findKey(char16_t ch, int32_t* outKeyCode, int32_t* outMetaState) const;
231
232    static status_t load(Tokenizer* tokenizer, Format format, sp<KeyCharacterMap>* outMap);
233
234    static void addKey(Vector<KeyEvent>& outEvents,
235            int32_t deviceId, int32_t keyCode, int32_t metaState, bool down, nsecs_t time);
236    static void addMetaKeys(Vector<KeyEvent>& outEvents,
237            int32_t deviceId, int32_t metaState, bool down, nsecs_t time,
238            int32_t* currentMetaState);
239    static bool addSingleEphemeralMetaKey(Vector<KeyEvent>& outEvents,
240            int32_t deviceId, int32_t metaState, bool down, nsecs_t time,
241            int32_t keyCode, int32_t keyMetaState,
242            int32_t* currentMetaState);
243    static void addDoubleEphemeralMetaKey(Vector<KeyEvent>& outEvents,
244            int32_t deviceId, int32_t metaState, bool down, nsecs_t time,
245            int32_t leftKeyCode, int32_t leftKeyMetaState,
246            int32_t rightKeyCode, int32_t rightKeyMetaState,
247            int32_t eitherKeyMetaState,
248            int32_t* currentMetaState);
249    static void addLockedMetaKey(Vector<KeyEvent>& outEvents,
250            int32_t deviceId, int32_t metaState, nsecs_t time,
251            int32_t keyCode, int32_t keyMetaState,
252            int32_t* currentMetaState);
253};
254
255} // namespace android
256
257#endif // _ANDROIDFW_KEY_CHARACTER_MAP_H
258