PointerController.h revision fe9f8ab03a63b1037f07dd85799fbea80ec6adaa 
1/*
2 * Copyright (C) 2010 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 _UI_POINTER_CONTROLLER_H
18#define _UI_POINTER_CONTROLLER_H
19
20#include "SpriteController.h"
21
22#include <ui/DisplayInfo.h>
23#include <ui/Input.h>
24#include <utils/RefBase.h>
25#include <utils/Looper.h>
26#include <utils/String8.h>
27
28#include <SkBitmap.h>
29
30namespace android {
31
32/**
33 * Interface for tracking a mouse / touch pad pointer and touch pad spots.
34 *
35 * The spots are sprites on screen that visually represent the positions of
36 * fingers
37 *
38 * The pointer controller is responsible for providing synchronization and for tracking
39 * display orientation changes if needed.
40 */
41class PointerControllerInterface : public virtual RefBase {
42protected:
43    PointerControllerInterface() { }
44    virtual ~PointerControllerInterface() { }
45
46public:
47    /* Gets the bounds of the region that the pointer can traverse.
48     * Returns true if the bounds are available. */
49    virtual bool getBounds(float* outMinX, float* outMinY,
50            float* outMaxX, float* outMaxY) const = 0;
51
52    /* Move the pointer. */
53    virtual void move(float deltaX, float deltaY) = 0;
54
55    /* Sets a mask that indicates which buttons are pressed. */
56    virtual void setButtonState(int32_t buttonState) = 0;
57
58    /* Gets a mask that indicates which buttons are pressed. */
59    virtual int32_t getButtonState() const = 0;
60
61    /* Sets the absolute location of the pointer. */
62    virtual void setPosition(float x, float y) = 0;
63
64    /* Gets the absolute location of the pointer. */
65    virtual void getPosition(float* outX, float* outY) const = 0;
66
67    /* Fades the pointer out now. */
68    virtual void fade() = 0;
69
70    /* Makes the pointer visible if it has faded out.
71     * The pointer never unfades itself automatically.  This method must be called
72     * by the client whenever the pointer is moved or a button is pressed and it
73     * wants to ensure that the pointer becomes visible again. */
74    virtual void unfade() = 0;
75
76    enum Presentation {
77        // Show the mouse pointer.
78        PRESENTATION_POINTER,
79        // Show spots and a spot anchor in place of the mouse pointer.
80        PRESENTATION_SPOT,
81    };
82
83    /* Sets the mode of the pointer controller. */
84    virtual void setPresentation(Presentation presentation) = 0;
85
86    // Describes the current gesture.
87    enum SpotGesture {
88        // No gesture.
89        // Do not display any spots.
90        SPOT_GESTURE_NEUTRAL,
91        // Tap at current location.
92        // Briefly display one spot at the tapped location.
93        SPOT_GESTURE_TAP,
94        // Drag at current location.
95        // Display spot at pressed location.
96        SPOT_GESTURE_DRAG,
97        // Button pressed but no finger is down.
98        // Display spot at pressed location.
99        SPOT_GESTURE_BUTTON_CLICK,
100        // Button pressed and a finger is down.
101        // Display spot at pressed location.
102        SPOT_GESTURE_BUTTON_DRAG,
103        // One finger down and hovering.
104        // Display spot at the hovered location.
105        SPOT_GESTURE_HOVER,
106        // Two fingers down but not sure in which direction they are moving so we consider
107        // it a press at the pointer location.
108        // Display two spots near the pointer location.
109        SPOT_GESTURE_PRESS,
110        // Two fingers down and moving in same direction.
111        // Display two spots near the pointer location.
112        SPOT_GESTURE_SWIPE,
113        // Two or more fingers down and moving in arbitrary directions.
114        // Display two or more spots near the pointer location, one for each finger.
115        SPOT_GESTURE_FREEFORM,
116    };
117
118    /* Sets the spots for the current gesture.
119     * The spots are not subject to the inactivity timeout like the pointer
120     * itself it since they are expected to remain visible for so long as
121     * the fingers are on the touch pad.
122     *
123     * The values of the AMOTION_EVENT_AXIS_PRESSURE axis is significant.
124     * For spotCoords, pressure != 0 indicates that the spot's location is being
125     * pressed (not hovering).
126     */
127    virtual void setSpots(SpotGesture spotGesture,
128            const PointerCoords* spotCoords, const uint32_t* spotIdToIndex,
129            BitSet32 spotIdBits) = 0;
130
131    /* Removes all spots. */
132    virtual void clearSpots() = 0;
133};
134
135
136/*
137 * Pointer resources.
138 */
139struct PointerResources {
140    SpriteIcon spotHover;
141    SpriteIcon spotTouch;
142    SpriteIcon spotAnchor;
143};
144
145
146/*
147 * Pointer controller policy interface.
148 *
149 * The pointer controller policy is used by the pointer controller to interact with
150 * the Window Manager and other system components.
151 *
152 * The actual implementation is partially supported by callbacks into the DVM
153 * via JNI.  This interface is also mocked in the unit tests.
154 */
155class PointerControllerPolicyInterface : public virtual RefBase {
156protected:
157    PointerControllerPolicyInterface() { }
158    virtual ~PointerControllerPolicyInterface() { }
159
160public:
161    virtual void loadPointerResources(PointerResources* outResources) = 0;
162};
163
164
165/*
166 * Tracks pointer movements and draws the pointer sprite to a surface.
167 *
168 * Handles pointer acceleration and animation.
169 */
170class PointerController : public PointerControllerInterface, public MessageHandler {
171protected:
172    virtual ~PointerController();
173
174public:
175    enum InactivityTimeout {
176        INACTIVITY_TIMEOUT_NORMAL = 0,
177        INACTIVITY_TIMEOUT_SHORT = 1,
178    };
179
180    PointerController(const sp<PointerControllerPolicyInterface>& policy,
181            const sp<Looper>& looper, const sp<SpriteController>& spriteController);
182
183    virtual bool getBounds(float* outMinX, float* outMinY,
184            float* outMaxX, float* outMaxY) const;
185    virtual void move(float deltaX, float deltaY);
186    virtual void setButtonState(int32_t buttonState);
187    virtual int32_t getButtonState() const;
188    virtual void setPosition(float x, float y);
189    virtual void getPosition(float* outX, float* outY) const;
190    virtual void fade();
191    virtual void unfade();
192
193    virtual void setPresentation(Presentation presentation);
194    virtual void setSpots(SpotGesture spotGesture,
195            const PointerCoords* spotCoords, const uint32_t* spotIdToIndex, BitSet32 spotIdBits);
196    virtual void clearSpots();
197
198    void setDisplaySize(int32_t width, int32_t height);
199    void setDisplayOrientation(int32_t orientation);
200    void setPointerIcon(const SpriteIcon& icon);
201    void setInactivityTimeout(InactivityTimeout inactivityTimeout);
202
203private:
204    static const size_t MAX_RECYCLED_SPRITES = 12;
205    static const size_t MAX_SPOTS = 12;
206
207    enum {
208        MSG_ANIMATE,
209        MSG_INACTIVITY_TIMEOUT,
210    };
211
212    struct Spot {
213        static const uint32_t INVALID_ID = 0xffffffff;
214
215        uint32_t id;
216        sp<Sprite> sprite;
217        float alpha;
218        float scale;
219        float x, y;
220
221        inline Spot(uint32_t id, const sp<Sprite>& sprite)
222                : id(id), sprite(sprite), alpha(1.0f), scale(1.0f),
223                  x(0.0f), y(0.0f), lastIcon(NULL) { }
224
225        void updateSprite(const SpriteIcon* icon, float x, float y);
226
227    private:
228        const SpriteIcon* lastIcon;
229    };
230
231    mutable Mutex mLock;
232
233    sp<PointerControllerPolicyInterface> mPolicy;
234    sp<Looper> mLooper;
235    sp<SpriteController> mSpriteController;
236    sp<WeakMessageHandler> mHandler;
237
238    PointerResources mResources;
239
240    struct Locked {
241        bool animationPending;
242        nsecs_t animationTime;
243
244        int32_t displayWidth;
245        int32_t displayHeight;
246        int32_t displayOrientation;
247
248        InactivityTimeout inactivityTimeout;
249
250        Presentation presentation;
251        bool presentationChanged;
252
253        bool pointerIsFading;
254        float pointerX;
255        float pointerY;
256        float pointerAlpha;
257        sp<Sprite> pointerSprite;
258        SpriteIcon pointerIcon;
259        bool pointerIconChanged;
260
261        int32_t buttonState;
262
263        Vector<Spot*> spots;
264        Vector<sp<Sprite> > recycledSprites;
265    } mLocked;
266
267    bool getBoundsLocked(float* outMinX, float* outMinY, float* outMaxX, float* outMaxY) const;
268    void setPositionLocked(float x, float y);
269
270    void handleMessage(const Message& message);
271    void doAnimate();
272    void doInactivityTimeout();
273
274    void startAnimationLocked();
275
276    void resetInactivityTimeoutLocked();
277    void sendImmediateInactivityTimeoutLocked();
278    void updatePointerLocked();
279
280    Spot* getSpotLocked(uint32_t id);
281    Spot* createAndAddSpotLocked(uint32_t id);
282    Spot* removeFirstFadingSpotLocked();
283    void releaseSpotLocked(Spot* spot);
284    void fadeOutAndReleaseSpotLocked(Spot* spot);
285    void fadeOutAndReleaseAllSpotsLocked();
286
287    void loadResources();
288};
289
290} // namespace android
291
292#endif // _UI_POINTER_CONTROLLER_H
293