PointerController.h revision 2352b978a3c94cd88f41d0d908f961333fdac1e9 
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(uint32_t buttonState) = 0;
57
58    /* Gets a mask that indicates which buttons are pressed. */
59    virtual uint32_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        // Button pressed but no finger is down.
95        // Display spot at pressed location.
96        SPOT_GESTURE_BUTTON_CLICK,
97        // Button pressed and a finger is down.
98        // Display spot at pressed location.
99        SPOT_GESTURE_BUTTON_DRAG,
100        // One finger down and hovering.
101        // Display spot at the hovered location.
102        SPOT_GESTURE_HOVER,
103        // Two fingers down but not sure in which direction they are moving so we consider
104        // it a press at the pointer location.
105        // Display two spots near the pointer location.
106        SPOT_GESTURE_PRESS,
107        // Two fingers down and moving in same direction.
108        // Display two spots near the pointer location.
109        SPOT_GESTURE_SWIPE,
110        // Two or more fingers down and moving in arbitrary directions.
111        // Display two or more spots near the pointer location, one for each finger.
112        SPOT_GESTURE_FREEFORM,
113    };
114
115    /* Sets the spots for the current gesture.
116     * The spots are not subject to the inactivity timeout like the pointer
117     * itself it since they are expected to remain visible for so long as
118     * the fingers are on the touch pad.
119     *
120     * The values of the AMOTION_EVENT_AXIS_PRESSURE axis is significant.
121     * For spotCoords, pressure != 0 indicates that the spot's location is being
122     * pressed (not hovering).
123     */
124    virtual void setSpots(SpotGesture spotGesture,
125            const PointerCoords* spotCoords, const uint32_t* spotIdToIndex,
126            BitSet32 spotIdBits) = 0;
127
128    /* Removes all spots. */
129    virtual void clearSpots() = 0;
130};
131
132
133/*
134 * Pointer resources.
135 */
136struct PointerResources {
137    SpriteIcon spotHover;
138    SpriteIcon spotTouch;
139    SpriteIcon spotAnchor;
140};
141
142
143/*
144 * Pointer controller policy interface.
145 *
146 * The pointer controller policy is used by the pointer controller to interact with
147 * the Window Manager and other system components.
148 *
149 * The actual implementation is partially supported by callbacks into the DVM
150 * via JNI.  This interface is also mocked in the unit tests.
151 */
152class PointerControllerPolicyInterface : public virtual RefBase {
153protected:
154    PointerControllerPolicyInterface() { }
155    virtual ~PointerControllerPolicyInterface() { }
156
157public:
158    virtual void loadPointerResources(PointerResources* outResources) = 0;
159};
160
161
162/*
163 * Tracks pointer movements and draws the pointer sprite to a surface.
164 *
165 * Handles pointer acceleration and animation.
166 */
167class PointerController : public PointerControllerInterface, public MessageHandler {
168protected:
169    virtual ~PointerController();
170
171public:
172    enum InactivityTimeout {
173        INACTIVITY_TIMEOUT_NORMAL = 0,
174        INACTIVITY_TIMEOUT_SHORT = 1,
175    };
176
177    PointerController(const sp<PointerControllerPolicyInterface>& policy,
178            const sp<Looper>& looper, const sp<SpriteController>& spriteController);
179
180    virtual bool getBounds(float* outMinX, float* outMinY,
181            float* outMaxX, float* outMaxY) const;
182    virtual void move(float deltaX, float deltaY);
183    virtual void setButtonState(uint32_t buttonState);
184    virtual uint32_t getButtonState() const;
185    virtual void setPosition(float x, float y);
186    virtual void getPosition(float* outX, float* outY) const;
187    virtual void fade();
188    virtual void unfade();
189
190    virtual void setPresentation(Presentation presentation);
191    virtual void setSpots(SpotGesture spotGesture,
192            const PointerCoords* spotCoords, const uint32_t* spotIdToIndex, BitSet32 spotIdBits);
193    virtual void clearSpots();
194
195    void setDisplaySize(int32_t width, int32_t height);
196    void setDisplayOrientation(int32_t orientation);
197    void setPointerIcon(const SpriteIcon& icon);
198    void setInactivityTimeout(InactivityTimeout inactivityTimeout);
199
200private:
201    static const size_t MAX_RECYCLED_SPRITES = 12;
202    static const size_t MAX_SPOTS = 12;
203
204    enum {
205        MSG_ANIMATE,
206        MSG_INACTIVITY_TIMEOUT,
207    };
208
209    struct Spot {
210        static const uint32_t INVALID_ID = 0xffffffff;
211
212        uint32_t id;
213        sp<Sprite> sprite;
214        float alpha;
215        float scale;
216        float x, y;
217
218        inline Spot(uint32_t id, const sp<Sprite>& sprite)
219                : id(id), sprite(sprite), alpha(1.0f), scale(1.0f),
220                  x(0.0f), y(0.0f), lastIcon(NULL) { }
221
222        void updateSprite(const SpriteIcon* icon, float x, float y);
223
224    private:
225        const SpriteIcon* lastIcon;
226    };
227
228    mutable Mutex mLock;
229
230    sp<PointerControllerPolicyInterface> mPolicy;
231    sp<Looper> mLooper;
232    sp<SpriteController> mSpriteController;
233    sp<WeakMessageHandler> mHandler;
234
235    PointerResources mResources;
236
237    struct Locked {
238        bool animationPending;
239        nsecs_t animationTime;
240
241        int32_t displayWidth;
242        int32_t displayHeight;
243        int32_t displayOrientation;
244
245        InactivityTimeout inactivityTimeout;
246
247        Presentation presentation;
248        bool presentationChanged;
249
250        bool pointerIsFading;
251        float pointerX;
252        float pointerY;
253        float pointerAlpha;
254        sp<Sprite> pointerSprite;
255        SpriteIcon pointerIcon;
256        bool pointerIconChanged;
257
258        uint32_t buttonState;
259
260        Vector<Spot*> spots;
261        Vector<sp<Sprite> > recycledSprites;
262    } mLocked;
263
264    bool getBoundsLocked(float* outMinX, float* outMinY, float* outMaxX, float* outMaxY) const;
265    void setPositionLocked(float x, float y);
266
267    void handleMessage(const Message& message);
268    void doAnimate();
269    void doInactivityTimeout();
270
271    void startAnimationLocked();
272
273    void resetInactivityTimeoutLocked();
274    void sendImmediateInactivityTimeoutLocked();
275    void updatePointerLocked();
276
277    Spot* getSpotLocked(uint32_t id);
278    Spot* createAndAddSpotLocked(uint32_t id);
279    Spot* removeFirstFadingSpotLocked();
280    void releaseSpotLocked(Spot* spot);
281    void fadeOutAndReleaseSpotLocked(Spot* spot);
282    void fadeOutAndReleaseAllSpotsLocked();
283
284    void loadResources();
285};
286
287} // namespace android
288
289#endif // _UI_POINTER_CONTROLLER_H
290