add android_broadcast module

tito · tito · commit 075a46598ada · 2013-04-28T23:06:15.000+02:00
diff --git a/docs/source/android.rst b/docs/source/android.rst
@@ -348,6 +348,84 @@ Example without PyJNIus
     print android.get_dpi()
 
 
+Bridges
+-------
+
+Some part of the Android API is not accessible from PyJNIus. For example, if
+you want to receive some broadcast, you need to implement a `BroadcastReceiver
+<http://developer.android.com/reference/android/content/BroadcastReceiver.html>`_.
+PyJNIus allows you to implement dynamically classes from Java interfaces, but
+unfortunately, the `BroadcastReceiver` is an abstract class.
+
+So we started to create bridges for this case.
+
+android_broadcast
+~~~~~~~~~~~~~~~~~
+
+.. module:: android_broadcast
+
+.. class:: BroadcastReceiver
+
+    Implementation of the android `BroadcastReceiver
+    <http://developer.android.com/reference/android/content/BroadcastReceiver.html>`_.
+    You can specify the callback that will receive the broadcast event, and
+    actions or categories filters.
+
+    .. warning::
+
+        The callback will be called in another thread than the main thread. Be
+        careful to not access to OpenGL or something like that.
+
+    .. method:: __init__(callback, actions=None, categories=None)
+
+        :param callback: function or method that will receive the event. Will
+                         receive the context and intent as argument.
+        :param actions: list of strings that represent an action.
+        :param categories: list of strings that represent a category.
+
+        For actions and categories, the string must be in lower case, without the prefix::
+
+            # In java: Intent.ACTION_HEADSET_PLUG
+            # In python: 'headset_plug'
+
+    .. method:: start()
+
+        Register the receiver with all the actions and categories, and start
+        handling events.
+
+    .. method:: stop()
+
+        Unregister the receiver with all the actions and categories, and stop
+        handling events.
+
+Example::
+
+    class TestApp(App):
+
+        def build(self):
+            self.br = BroadcastReceiver(
+                self.on_broadcast, actions=['headset_plug'])
+            self.br.start()
+            # ...
+
+        def on_broadcast(self, context, intent):
+            extras = intent.getExtras()
+            headset_state = bool(extras.get('state'))
+            if headset_state:
+                print 'The headset is plugged'
+            else:
+                print 'The headset is unplugged'
+
+        # don't forget to stop and restart the receiver when the app is going
+        # to pause / resume mode
+
+        def on_pause(self):
+            self.br.stop()
+            return True
+
+        def on_resume(self):
+            self.br.start()
+
 
 Old Version
 -----------
@@ -434,3 +512,4 @@ It has several differences from the pygame mixer:
     The android_mixer module hasn't been tested much, and so bugs may be
     present.
 
+
diff --git a/recipes/android/src/android_broadcast.py b/recipes/android/src/android_broadcast.py
@@ -0,0 +1,75 @@
+# -------------------------------------------------------------------
+# Broadcast receiver bridge
+
+from jnius import autoclass, PythonJavaClass, java_method
+
+class BroadcastReceiver(object):
+
+    class Callback(PythonJavaClass):
+        __javainterfaces__ = ['org/renpy/android/GenericBroadcastReceiverCallback']
+        __javacontext__ = 'app'
+
+        def __init__(self, callback, *args, **kwargs):
+            self.callback = callback
+            PythonJavaClass.__init__(self, *args, **kwargs)
+
+        @java_method('(Landroid/content/Context;Landroid/content/Intent;)V')
+        def onReceive(self, context, intent):
+            self.callback(context, intent)
+
+    def __init__(self, callback, actions=None, categories=None):
+        super(BroadcastReceiver, self).__init__()
+        self.callback = callback
+
+        if not actions and not categories:
+            raise Exception('You need to define at least actions or categories')
+
+        # resolve actions/categories first
+        Intent = autoclass('android.content.Intent')
+        resolved_actions = []
+        if actions:
+            for x in actions:
+                name = 'ACTION_{}'.format(x.upper())
+                if not hasattr(Intent, name):
+                    raise Exception('The intent {} doesnt exist'.format(name))
+                resolved_actions += [getattr(Intent, name)]
+
+        resolved_categories = []
+        if categories:
+            for x in categories:
+                name = 'CATEGORY_{}'.format(x.upper())
+                if not hasattr(Intent, name):
+                    raise Exception('The intent {} doesnt exist'.format(name))
+                resolved_categories += [getattr(Intent, name)]
+
+        # resolve android API
+        PythonActivity = autoclass('org.renpy.android.PythonActivity')
+        GenericBroadcastReceiver = autoclass('org.renpy.android.GenericBroadcastReceiver')
+        IntentFilter = autoclass('android.content.IntentFilter')
+        HandlerThread = autoclass('android.os.HandlerThread')
+
+        # create a thread for handling events from the receiver
+        self.handlerthread = HandlerThread('handlerthread')
+
+        # create a listener
+        self.context = PythonActivity.mActivity
+        self.listener = BroadcastReceiver.Callback(self.callback)
+        self.receiver = GenericBroadcastReceiver(self.listener)
+        self.receiver_filter = IntentFilter()
+        for x in resolved_actions:
+            self.receiver_filter.addAction(x)
+        for x in resolved_categories:
+            self.receiver_filter.addCategory(x)
+
+    def start(self):
+        Handler = autoclass('android.os.Handler')
+        self.handlerthread.start()
+        self.handler = Handler(self.handlerthread.getLooper())
+        self.context.registerReceiver(self.receiver, self.receiver_filter, None,
+                self.handler)
+
+    def stop(self):
+        self.context.unregisterReceiver(self.receiver)
+        self.handlerthread.quit()
+
+
diff --git a/src/src/org/renpy/android/GenericBroadcastReceiver.java b/src/src/org/renpy/android/GenericBroadcastReceiver.java
@@ -0,0 +1,19 @@
+package org.renpy.android;
+
+import android.content.BroadcastReceiver;
+import android.content.Intent;
+import android.content.Context;
+
+public class GenericBroadcastReceiver extends BroadcastReceiver {
+
+	GenericBroadcastReceiverCallback listener;
+
+	public GenericBroadcastReceiver(GenericBroadcastReceiverCallback listener) {
+		super();
+		this.listener = listener;
+	}
+
+	public void onReceive(Context context, Intent intent) {
+		this.listener.onReceive(context, intent);
+	}
+}
diff --git a/src/src/org/renpy/android/GenericBroadcastReceiverCallback.java b/src/src/org/renpy/android/GenericBroadcastReceiverCallback.java
@@ -0,0 +1,8 @@
+package org.renpy.android;
+
+import android.content.Intent;
+import android.content.Context;
+
+public interface GenericBroadcastReceiverCallback {
+	void onReceive(Context context, Intent intent);
+};
