KeyCharacterMap.h revision 9f25b7fdf216c9ef0bd2322cd223eeaf0d60f77f 
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    };
53
54    // Substitute key code and meta state for fallback action.
55    struct FallbackAction {
56        int32_t keyCode;
57        int32_t metaState;
58    };
59
60    /* Loads a key character map from a file. */
61    static status_t load(const String8& filename, sp<KeyCharacterMap>* outMap);
62
63    /* Returns an empty key character map. */
64    static sp<KeyCharacterMap> empty();
65
66    /* Gets the keyboard type. */
67    int32_t getKeyboardType() const;
68
69    /* Gets the primary character for this key as in the label physically printed on it.
70     * Returns 0 if none (eg. for non-printing keys). */
71    char16_t getDisplayLabel(int32_t keyCode) const;
72
73    /* Gets the Unicode character for the number or symbol generated by the key
74     * when the keyboard is used as a dialing pad.
75     * Returns 0 if no number or symbol is generated.
76     */
77    char16_t getNumber(int32_t keyCode) const;
78
79    /* Gets the Unicode character generated by the key and meta key modifiers.
80     * Returns 0 if no character is generated.
81     */
82    char16_t getCharacter(int32_t keyCode, int32_t metaState) const;
83
84    /* Gets the fallback action to use by default if the application does not
85     * handle the specified key.
86     * Returns true if an action was available, false if none.
87     */
88    bool getFallbackAction(int32_t keyCode, int32_t metaState,
89            FallbackAction* outFallbackAction) const;
90
91    /* Gets the first matching Unicode character that can be generated by the key,
92     * preferring the one with the specified meta key modifiers.
93     * Returns 0 if no matching character is generated.
94     */
95    char16_t getMatch(int32_t keyCode, const char16_t* chars,
96            size_t numChars, int32_t metaState) const;
97
98    /* Gets a sequence of key events that could plausibly generate the specified
99     * character sequence.  Returns false if some of the characters cannot be generated.
100     */
101    bool getEvents(int32_t deviceId, const char16_t* chars, size_t numChars,
102            Vector<KeyEvent>& outEvents) const;
103
104#if HAVE_ANDROID_OS
105    /* Reads a key map from a parcel. */
106    static sp<KeyCharacterMap> readFromParcel(Parcel* parcel);
107
108    /* Writes a key map to a parcel. */
109    void writeToParcel(Parcel* parcel) const;
110#endif
111
112protected:
113    virtual ~KeyCharacterMap();
114
115private:
116    struct Behavior {
117        Behavior();
118
119        /* The next behavior in the list, or NULL if none. */
120        Behavior* next;
121
122        /* The meta key modifiers for this behavior. */
123        int32_t metaState;
124
125        /* The character to insert. */
126        char16_t character;
127
128        /* The fallback keycode if the key is not handled. */
129        int32_t fallbackKeyCode;
130    };
131
132    struct Key {
133        Key();
134        ~Key();
135
136        /* The single character label printed on the key, or 0 if none. */
137        char16_t label;
138
139        /* The number or symbol character generated by the key, or 0 if none. */
140        char16_t number;
141
142        /* The list of key behaviors sorted from most specific to least specific
143         * meta key binding. */
144        Behavior* firstBehavior;
145    };
146
147    class Parser {
148        enum State {
149            STATE_TOP = 0,
150            STATE_KEY = 1,
151        };
152
153        enum {
154            PROPERTY_LABEL = 1,
155            PROPERTY_NUMBER = 2,
156            PROPERTY_META = 3,
157        };
158
159        struct Property {
160            inline Property(int32_t property = 0, int32_t metaState = 0) :
161                    property(property), metaState(metaState) { }
162
163            int32_t property;
164            int32_t metaState;
165        };
166
167        KeyCharacterMap* mMap;
168        Tokenizer* mTokenizer;
169        State mState;
170        int32_t mKeyCode;
171
172    public:
173        Parser(KeyCharacterMap* map, Tokenizer* tokenizer);
174        ~Parser();
175        status_t parse();
176
177    private:
178        status_t parseType();
179        status_t parseKey();
180        status_t parseKeyProperty();
181        status_t parseModifier(const String8& token, int32_t* outMetaState);
182        status_t parseCharacterLiteral(char16_t* outCharacter);
183    };
184
185    static sp<KeyCharacterMap> sEmpty;
186
187    KeyedVector<int32_t, Key*> mKeys;
188    int mType;
189
190    KeyCharacterMap();
191
192    bool getKey(int32_t keyCode, const Key** outKey) const;
193    bool getKeyBehavior(int32_t keyCode, int32_t metaState,
194            const Key** outKey, const Behavior** outBehavior) const;
195
196    bool findKey(char16_t ch, int32_t* outKeyCode, int32_t* outMetaState) const;
197
198    static void addKey(Vector<KeyEvent>& outEvents,
199            int32_t deviceId, int32_t keyCode, int32_t metaState, bool down, nsecs_t time);
200    static void addMetaKeys(Vector<KeyEvent>& outEvents,
201            int32_t deviceId, int32_t metaState, bool down, nsecs_t time,
202            int32_t* currentMetaState);
203    static bool addSingleEphemeralMetaKey(Vector<KeyEvent>& outEvents,
204            int32_t deviceId, int32_t metaState, bool down, nsecs_t time,
205            int32_t keyCode, int32_t keyMetaState,
206            int32_t* currentMetaState);
207    static void addDoubleEphemeralMetaKey(Vector<KeyEvent>& outEvents,
208            int32_t deviceId, int32_t metaState, bool down, nsecs_t time,
209            int32_t leftKeyCode, int32_t leftKeyMetaState,
210            int32_t rightKeyCode, int32_t rightKeyMetaState,
211            int32_t eitherKeyMetaState,
212            int32_t* currentMetaState);
213    static void addLockedMetaKey(Vector<KeyEvent>& outEvents,
214            int32_t deviceId, int32_t metaState, nsecs_t time,
215            int32_t keyCode, int32_t keyMetaState,
216            int32_t* currentMetaState);
217};
218
219} // namespace android
220
221#endif // _ANDROIDFW_KEY_CHARACTER_MAP_H
222