在不同的 Android 系統(tǒng)版本支持控制器

編寫:heray1990 - 原文:http://developer.android.com/training/game-controllers/compatibility.html

如果我們正為游戲提供游戲控制器的支持，那么我們需要確保我們的游戲?qū)τ谶\(yùn)行著不同 Android 版本的設(shè)備對(duì)控制器都有一致的響應(yīng)。這會(huì)使得我們的游戲擴(kuò)大用戶群體，同時(shí)，我們的玩家可以享受即使他們切換或者升級(jí) Android 設(shè)備的時(shí)候，都可以使用他們的控制器無縫對(duì)接的游戲體驗(yàn)。

這節(jié)課展示了如何用向下兼容的方式使用 Android 4.1 或者更高版本中可用的 API，使我們的游戲運(yùn)行在 Android 2.3 或者更高的設(shè)備上時(shí)，支持下面的功能：

• 游戲可以檢測(cè)是否有一個(gè)新的游戲控制器接入、變更或者移除。
• 游戲可以查詢游戲控制器的兼容性。
• 游戲可以識(shí)別從游戲控制器傳入的動(dòng)作事件。

這節(jié)課的例子是基于 ControllerSample.zip 提供的參考實(shí)現(xiàn)。這個(gè)示例介紹了如何實(shí)現(xiàn) InputManagerCompat接口來支持不同的 Android 版本。我們必須使用 Android 4.1（API level 16）或者更高的版本來編譯這個(gè)示例代碼。一旦編譯完成，生成的示例 app 可以在任何運(yùn)行著 Android 2.3（API level 9）或者更高版本的設(shè)備上運(yùn)行。

準(zhǔn)備支持游戲控制器的抽象 API

假設(shè)我們想確定在運(yùn)行著 Android 2.3（API level 9）的設(shè)備上，游戲控制器的連接狀態(tài)是否發(fā)生改變。無論如何，API 只在 Android 4.1（API level 16）或者更高的版本上可用，所以我們需要提供一個(gè)支持 Android 4.1（API level 16）或者更高版本的實(shí)現(xiàn)方法的同時(shí)，提供一個(gè)支持從 Android 2.3 到 Android 4.0 的回退機(jī)制。

為了幫助我們確定哪個(gè)功能需要這樣的回退機(jī)制，table 1 列出了 Android 2.3（API level 9）、3.1（API level 12）和 4.1（API level 16）之間，對(duì)于支持游戲控制器的不同之處。

Table 1. API 在不同 Android 版本間對(duì)游戲控制器支持的不同點(diǎn)

我們可以使用抽象化概念來建立能夠工作在不同平臺(tái)的版本識(shí)別的游戲控制器支持。這種方法包括下面幾個(gè)步驟：

1. 定義一個(gè)中間 Java 接口來抽象化我們游戲需要的游戲控制器功能的實(shí)現(xiàn)。

2. 創(chuàng)建一個(gè)使用 Android 4.1 和更高版本 API 的接口的代理實(shí)現(xiàn)。

3. 創(chuàng)建一個(gè)使用 Android 2.3 到 Android 4.0 之間可用的 API 的接口的自定義實(shí)現(xiàn)。

4. 創(chuàng)建在運(yùn)行時(shí)，在這上述這些實(shí)現(xiàn)之間切換的邏輯，并且開始使用我們游戲中的接口。

有關(guān)如何使用抽象化概念來保證應(yīng)用可以在不同版本的 Android 之間，以向后兼容的方式工作的概述，請(qǐng)見創(chuàng)建向后兼容的 UI。

添加向后兼容的接口

對(duì)于向后兼容，我們可以創(chuàng)建一個(gè)自定義接口，然后添加特定版本的實(shí)現(xiàn)。這種方法的一個(gè)優(yōu)點(diǎn)是它可以讓我們借鑒 Android 4.1（API level 16）上支持游戲控制器的公共接口。

// The InputManagerCompat interface is a reference example.
// The full code is provided in the ControllerSample.zip sample.
public interface InputManagerCompat {
    ...
    public InputDevice getInputDevice(int id);
    public int[] getInputDeviceIds();

    public void registerInputDeviceListener(
            InputManagerCompat.InputDeviceListener listener,
            Handler handler);
    public void unregisterInputDeviceListener(
            InputManagerCompat.InputDeviceListener listener);

    public void onGenericMotionEvent(MotionEvent event);

    public void onPause();
    public void onResume();

    public interface InputDeviceListener {
        void onInputDeviceAdded(int deviceId);
        void onInputDeviceChanged(int deviceId);
        void onInputDeviceRemoved(int deviceId);
    }
    ...
}

InputManagerCompat 接口提供了下面的方法：

getInputDevice()

借鑒 getInputDevice()。包括代表一個(gè)游戲控制器兼容性的 InputDevice 對(duì)象。

getInputDeviceIds()

借鑒getInputDeviceIds()。返回一個(gè)整型數(shù)組，每一個(gè)數(shù)組成員表示一個(gè)不同輸入設(shè)備的 ID。這對(duì)于想要構(gòu)建一個(gè)支持多玩家和檢測(cè)連接了多少個(gè)控制器的游戲是很有用的。

registerInputDeviceListener()

借鑒registerInputDeviceListener()。注冊(cè)一個(gè)監(jiān)聽器，當(dāng)一個(gè)新的設(shè)備添加、改變或者移除的時(shí)候，我們會(huì)收到通知。

unregisterInputDeviceListener()

借鑒unregisterInputDeviceListener()。注銷一個(gè)輸入設(shè)備監(jiān)聽器。

onGenericMotionEvent()

借鑒onGenericMotionEvent()。讓我們的游戲截取和處理 MotionEvent 對(duì)象和代表類似移動(dòng)搖桿和按下模擬觸發(fā)器等事件的坐標(biāo)值。

onPause()

當(dāng)主 activity 暫停或者當(dāng)游戲不再聚焦時(shí)，停止輪詢游戲控制器事件。

onResume()

當(dāng)主 activity 恢復(fù)或者當(dāng)游戲開始和在前臺(tái)運(yùn)行時(shí)，啟動(dòng)輪詢游戲控制器事件。

InputDeviceListener

借鑒 InputManager.InputDeviceListener 接口。當(dāng)添加、改變或者移除游戲控制器時(shí)，會(huì)通知我們的游戲。

下一步，創(chuàng)建 InputManagerCompat 的實(shí)現(xiàn)，使得可以在不同平臺(tái)版本間工作。如果我們的游戲運(yùn)行在 Android 4.1 或者更高版本，調(diào)用 InputManagerCompat 方法，代理實(shí)現(xiàn)調(diào)用在 InputManager 中等效的方法。然而，如果我們的游戲運(yùn)行在 Andoird 2.3 到 Android 4.0，自定義的實(shí)現(xiàn)過程通過使用不晚于 Android 2.3 引進(jìn)的 API 來調(diào)用 InputManagerCompat 方法。不管在運(yùn)行時(shí)使用哪種特定版本的實(shí)現(xiàn)，實(shí)現(xiàn)會(huì)透明地將回調(diào)結(jié)果傳給游戲。

Figure 1. 接口和特定版本實(shí)現(xiàn)的類圖。

實(shí)現(xiàn) Android 4.1 和更高版本的接口

InputManagerCompatV16 是 InputManagerCompat 接口的實(shí)現(xiàn)，該接口代理方法調(diào)用一個(gè) InputManager 和 InputManager.InputDeviceListener。InputManager是從系統(tǒng) Context 得到。

// The InputManagerCompatV16 class is a reference implementation.
// The full code is provided in the ControllerSample.zip sample.
public class InputManagerV16 implements InputManagerCompat {

    private final InputManager mInputManager;
    private final Map mListeners;

    public InputManagerV16(Context context) {
        mInputManager = (InputManager)
                context.getSystemService(Context.INPUT_SERVICE);
        mListeners = new HashMap();
    }

    @Override
    public InputDevice getInputDevice(int id) {
        return mInputManager.getInputDevice(id);
    }

    @Override
    public int[] getInputDeviceIds() {
        return mInputManager.getInputDeviceIds();
    }

    static class V16InputDeviceListener implements
            InputManager.InputDeviceListener {
        final InputManagerCompat.InputDeviceListener mIDL;

        public V16InputDeviceListener(InputDeviceListener idl) {
            mIDL = idl;
        }

        @Override
        public void onInputDeviceAdded(int deviceId) {
            mIDL.onInputDeviceAdded(deviceId);
        }

        // Do the same for device change and removal
        ...
    }

    @Override
    public void registerInputDeviceListener(InputDeviceListener listener,
            Handler handler) {
        V16InputDeviceListener v16Listener = new
                V16InputDeviceListener(listener);
        mInputManager.registerInputDeviceListener(v16Listener, handler);
        mListeners.put(listener, v16Listener);
    }

    // Do the same for unregistering an input device listener
    ...

    @Override
    public void onGenericMotionEvent(MotionEvent event) {
        // unused in V16
    }

    @Override
    public void onPause() {
        // unused in V16
    }

    @Override
    public void onResume() {
        // unused in V16
    }

}

實(shí)現(xiàn) Android 2.3 到 Android 4.0 的接口

InputManagerV9 實(shí)現(xiàn)使用了不晚于 Android 2.3 引進(jìn)的 API。為了創(chuàng)建一個(gè)支持 Android 2.3 到 Android 4.0 的 InputManagerCompat 實(shí)現(xiàn)，我們可以使用下面的對(duì)象：

• 設(shè)備 ID 的 SparseArray 跟蹤已連接到設(shè)備的游戲控制器。
• 一個(gè) Handler 來處理設(shè)備事件。當(dāng)一個(gè) app 啟動(dòng)或者恢復(fù)時(shí)，Handler 接收一個(gè)消息來開始輪詢游戲控制器的斷開。Handler 將啟動(dòng)一個(gè)循環(huán)來檢查每個(gè)已知連接的游戲控制器并且查看是否返回一個(gè)設(shè)備 ID。返回　null 表示游戲控制器斷開。當(dāng) app 暫停時(shí)，Handler 停止輪詢。
• 一個(gè) InputManagerCompat.InputDeviceListener 的 Map 對(duì)象。我們會(huì)使用這個(gè) listener 來更新跟蹤游戲遙控器的連接狀態(tài)。

// The InputManagerCompatV9 class is a reference implementation.
// The full code is provided in the ControllerSample.zip sample.
public class InputManagerV9 implements InputManagerCompat {
    private final SparseArray mDevices;
    private final Map mListeners;
    private final Handler mDefaultHandler;
    …

    public InputManagerV9() {
        mDevices = new SparseArray();
        mListeners = new HashMap();
        mDefaultHandler = new PollingMessageHandler(this);
    }
}

實(shí)現(xiàn)繼承 Handler 的 PollingMessageHandler，并重寫 handleMessage() 方法。這個(gè)方法檢查已連接的游戲控制器是否已經(jīng)斷開并且通知已注冊(cè)的 listener。

private static class PollingMessageHandler extends Handler {
    private final WeakReference mInputManager;

    PollingMessageHandler(InputManagerV9 im) {
        mInputManager = new WeakReference(im);
    }

    @Override
    public void handleMessage(Message msg) {
        super.handleMessage(msg);
        switch (msg.what) {
            case MESSAGE_TEST_FOR_DISCONNECT:
                InputManagerV9 imv = mInputManager.get();
                if (null != imv) {
                    long time = SystemClock.elapsedRealtime();
                    int size = imv.mDevices.size();
                    for (int i = 0; i < size; i++) {
                        long[] lastContact = imv.mDevices.valueAt(i);
                        if (null != lastContact) {
                            if (time - lastContact[0] > CHECK_ELAPSED_TIME) {
                                // check to see if the device has been
                                // disconnected
                                int id = imv.mDevices.keyAt(i);
                                if (null == InputDevice.getDevice(id)) {
                                    // Notify the registered listeners
                                    // that the game controller is disconnected
                                    ...
                                    imv.mDevices.remove(id);
                                } else {
                                    lastContact[0] = time;
                                }
                            }
                        }
                    }
                    sendEmptyMessageDelayed(MESSAGE_TEST_FOR_DISCONNECT,
                            CHECK_ELAPSED_TIME);
                }
                break;
        }
    }
}

至于啟動(dòng)和停止輪詢游戲控制器的斷開，重寫這些方法：

private static final int MESSAGE_TEST_FOR_DISCONNECT = 101;
private static final long CHECK_ELAPSED_TIME = 3000L;

@Override
public void onPause() {
    mDefaultHandler.removeMessages(MESSAGE_TEST_FOR_DISCONNECT);
}

@Override
public void onResume() {
    mDefaultHandler.sendEmptyMessageDelayed(MESSAGE_TEST_FOR_DISCONNECT,
            CHECK_ELAPSED_TIME);
}

重寫 onGenericMotionEvent() 方法檢測(cè)輸入設(shè)備是否已添加。當(dāng)系統(tǒng)通知一個(gè)動(dòng)作事件時(shí)，檢查這個(gè)事件是否從已經(jīng)跟蹤過的還是新的設(shè)備 ID 中發(fā)出。如果是新的設(shè)備 ID，通知已注冊(cè)的 listener。

@Override
public void onGenericMotionEvent(MotionEvent event) {
    // detect new devices
    int id = event.getDeviceId();
    long[] timeArray = mDevices.get(id);
    if (null == timeArray) {
        // Notify the registered listeners that a game controller is added
        ...
        timeArray = new long[1];
        mDevices.put(id, timeArray);
    }
    long time = SystemClock.elapsedRealtime();
    timeArray[0] = time;
}

listener 的通知通過使用 Handler 對(duì)象發(fā)送一個(gè) DeviceEvent Runnable 對(duì)象到消息隊(duì)列來實(shí)現(xiàn)。DeviceEvent 包含了一個(gè) InputManagerCompat.InputDeviceListener 的引用。當(dāng) DeviceEvent 運(yùn)行時(shí)，適當(dāng)?shù)?listener 回調(diào)方法會(huì)被調(diào)用，標(biāo)志游戲控制器是否被添加、改變或者移除。

@Override
public void registerInputDeviceListener(InputDeviceListener listener,
        Handler handler) {
    mListeners.remove(listener);
    if (handler == null) {
        handler = mDefaultHandler;
    }
    mListeners.put(listener, handler);
}

@Override
public void unregisterInputDeviceListener(InputDeviceListener listener) {
    mListeners.remove(listener);
}

private void notifyListeners(int why, int deviceId) {
    // the state of some device has changed
    if (!mListeners.isEmpty()) {
        for (InputDeviceListener listener : mListeners.keySet()) {
            Handler handler = mListeners.get(listener);
            DeviceEvent odc = DeviceEvent.getDeviceEvent(why, deviceId,
                    listener);
            handler.post(odc);
        }
    }
}

private static class DeviceEvent implements Runnable {
    private int mMessageType;
    private int mId;
    private InputDeviceListener mListener;
    private static Queue sObjectQueue =
            new ArrayDeque();
    ...

    static DeviceEvent getDeviceEvent(int messageType, int id,
            InputDeviceListener listener) {
        DeviceEvent curChanged = sObjectQueue.poll();
        if (null == curChanged) {
            curChanged = new DeviceEvent();
        }
        curChanged.mMessageType = messageType;
        curChanged.mId = id;
        curChanged.mListener = listener;
        return curChanged;
    }

    @Override
    public void run() {
        switch (mMessageType) {
            case ON_DEVICE_ADDED:
                mListener.onInputDeviceAdded(mId);
                break;
            case ON_DEVICE_CHANGED:
                mListener.onInputDeviceChanged(mId);
                break;
            case ON_DEVICE_REMOVED:
                mListener.onInputDeviceRemoved(mId);
                break;
            default:
                // Handle unknown message type
                ...
                break;
        }
        // Put this runnable back in the queue
        sObjectQueue.offer(this);
    }
}

我們現(xiàn)在已經(jīng)有兩個(gè) InputManagerCompat 的實(shí)現(xiàn)：一個(gè)可以在運(yùn)行 Android 4.1 或者更高版本的設(shè)備上工作，另一個(gè)可以在運(yùn)行 Android 2.3 到　Android 4.0 的設(shè)備上工作。

使用特定版本的實(shí)現(xiàn)

特定版本切換的邏輯是在一個(gè)充當(dāng) factory 的類中實(shí)現(xiàn)。

public static class Factory {
    public static InputManagerCompat getInputManager(Context context) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN) {
            return new InputManagerV16(context);
        } else {
            return new InputManagerV9();
        }
    }
}

現(xiàn)在我們可以簡(jiǎn)單地實(shí)例化一個(gè) InputManagerCompat 對(duì)象，并且在主 View 中注冊(cè) InputManagerCompat.InputDeviceListener。由于我們建立的版本切換邏輯，我們的游戲會(huì)自動(dòng)為設(shè)備上運(yùn)行的 Android 版本使用適當(dāng)?shù)膶?shí)現(xiàn)。

public class GameView extends View implements InputDeviceListener {
    private InputManagerCompat mInputManager;
    ...

    public GameView(Context context, AttributeSet attrs) {
        mInputManager =
                InputManagerCompat.Factory.getInputManager(this.getContext());
        mInputManager.registerInputDeviceListener(this, null);
        ...
    }
}

下一步，重寫主 View 的 onGenericMotionEvent() 方法，詳見處理從游戲控制器傳來的 MotionEvent。我們的游戲現(xiàn)在應(yīng)該可以一致地處理運(yùn)行著 Android 2.3（API level 9）和更高版本設(shè)備上的游戲控制器事件。

@Override
public boolean onGenericMotionEvent(MotionEvent event) {
    mInputManager.onGenericMotionEvent(event);

    // Handle analog input from the controller as normal
    ...
    return super.onGenericMotionEvent(event);
}

我們可以在上述的 ControllerSample.zip 示例的 GameView 類中找到這個(gè)兼容性的完整的代碼。