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