@@ -3,42 +3,40 @@ Accessing Android APIs
33======================
44
55When writing an Android application you may want to access the normal
6- Android APIs, which are available in Java. It is by calling these that
7- you would normally accomplish everything from vibration, to opening
8- other applications, to accessing sensor data, to controlling settings
9- like screen orientation and wakelocks.
10-
11- These APIs can be accessed from Python to perform all of these tasks
12- and many more. This is made possible by the `Pyjnius
13- <http://pyjnius.readthedocs.org/en/latest/> `_ module, a Python
14- library for automatically wrapping Java and making it callable from
15- Python code. This is fairly simple to use, though not very Pythonic
16- and inherits Java's verbosity. For this reason the Kivy organisation
17- also created `Plyer <https://plyer.readthedocs.org/en/latest/ >`_,
18- which further wraps specific APIs in a Pythonic and cross-platform
19- way - so in fact you can call the same code in Python but have it do
20- the right thing also on platforms other than Android.
21-
22- These are both independent projects whose documentation is linked
23- above, and you can check this to learn about all the things they can
24- do. The following sections give some simple introductory examples,
25- along with explanation of how to include these modules in your APKs.
6+ Android Java APIs, in order to control your application's appearance
7+ (fullscreen, orientation etc.), interact with other apps or use
8+ hardware like vibration and sensors.
9+
10+ You can access these with `Pyjnius
11+ <http://pyjnius.readthedocs.org/en/latest/> `_, a Python library for
12+ automatically wrapping Java and making it callable from Python
13+ code. Pyjnius is fairly simple to use, but not very Pythonic and it
14+ inherits Java's verbosity. For this reason the Kivy organisation also
15+ created `Plyer <https://plyer.readthedocs.org/en/latest/ >`_, which
16+ further wraps specific APIs in a Pythonic and cross-platform way; you
17+ can call the same code in Python but have it do the right thing also
18+ on platforms other than Android.
19+
20+ Pyjnius and Plyer are independent projects whose documentation is
21+ linked above. See below for some simple introductory examples, and
22+ explanation of how to include these modules in your APKs.
23+
24+ This page also documents the ``android `` module which you can include
25+ with p4a, but this is mostly replaced by Pyjnius and is not
26+ recommended for use in new applications.
2627
2728
2829Using Pyjnius
2930-------------
3031
31- Pyjnius lets you call the Android API directly from Python; this let's
32- you do almost everything you can (and probably would) do in a Java
33- app. Pyjnius is works by dynamically wrapping Java classes, so you
34- don't have to wait for any particular feature to be pre-supported.
32+ Pyjnius lets you call the Android API directly from Python Pyjnius is
33+ works by dynamically wrapping Java classes, so you don't have to wait
34+ for any particular feature to be pre-supported.
3535
36- You can include Pyjnius in your APKs by adding the `pyjnius ` or
37- `pyjniussdl2 ` recipes to your build requirements (the former works
38- with Pygame/SDL1, the latter with SDL2, the need to make this choice
39- will be removed later when pyjnius internally supports multiple
40- Android backends). It is automatically included in any APK containing
41- Kivy, in which case you don't need to specify it manually.
36+ You can include Pyjnius in your APKs by adding `pyjnius ` to your build
37+ requirements, e.g. :code: `--requirements=flask,pyjnius `. It is
38+ automatically included in any APK containing Kivy, in which case you
39+ don't need to specify it manually.
4240
4341The basic mechanism of Pyjnius is the `autoclass ` command, which wraps
4442a Java class. For instance, here is the code to vibrate your device::
@@ -87,17 +85,16 @@ You can check the `Pyjnius documentation <Pyjnius_>`_ for further details.
8785Using Plyer
8886-----------
8987
90- Plyer aims to provide a much less verbose, Pythonic wrapper to
91- platform-specific APIs. Android is a supported platform, but it also
92- supports iOS and desktop operating systems, with the idea that the
93- same Plyer code would do the right thing on any of them, though Plyer
94- is a work in progress and not all platforms support all Plyer calls
95- yet. This is the disadvantage of Plyer, it does not support all APIs
96- yet, but you can always Pyjnius to call anything that is currently
97- missing.
88+ Plyer provides a much less verbose, Pythonic wrapper to
89+ platform-specific APIs. It supports Android as well as iOS and desktop
90+ operating systems, though plyer is a work in progress and not all
91+ platforms support all Plyer calls yet.
92+
93+ Plyer does not support all APIs yet, but you can always Pyjnius to
94+ call anything that is currently missing.
9895
9996You can include Plyer in your APKs by adding the `Plyer ` recipe to
100- your build requirements. It is not included automatically.
97+ your build requirements, e.g. :code: ` --requirements=plyer `.
10198
10299You should check the `Plyer documentation <Plyer _>`_ for details of all supported
103100facades (platform APIs), but as an example the following is how you
@@ -106,8 +103,47 @@ would achieve vibration as described in the Pyjnius section above::
106103 from plyer.vibrator import vibrate
107104 vibrate(10) # in Plyer, the argument is in seconds
108105
109- This is obviously *much * less verbose!
106+ This is obviously *much * less verbose than with Pyjnius!
107+
108+
109+ Using ``android ``
110+ -----------------
111+
112+ This Cython module was used for Android API interaction with Kivy's old
113+ interface, but is now mostly replaced by Pyjnius.
114+
115+ The ``android `` Python module can be included by adding it to your
116+ requirements, e.g. :code: `--requirements=kivy,android `. It is not
117+ automatically included by Kivy unless you use the old (Pygame)
118+ bootstrap.
119+
120+ This module is not separately documented. You can read the source `on
121+ Github
122+ <https://github.com/kivy/python-for-android/tree/master/pythonforandroid/recipes/android/src/android> `__.
123+
124+ One useful facility of this module is to make
125+ :code: `webbrowser.open() ` work on Android. You can replicate this
126+ effect without using the android module via the following
127+ code::
128+
129+ from jnius import autoclass
130+
131+ def open_url(url):
132+ Intent = autoclass('android.content.Intent')
133+ Uri = autoclass('android.net.Uri')
134+ browserIntent = Intent()
135+ browserIntent.setAction(Intent.ACTION_VIEW)
136+ browserIntent.setData(Uri.parse(url))
137+ currentActivity = cast('android.app.Activity', mActivity)
138+ currentActivity.startActivity(browserIntent)
139+
140+ class AndroidBrowser(object):
141+ def open(self, url, new=0, autoraise=True):
142+ open_url(url)
143+ def open_new(self, url):
144+ open_url(url)
145+ def open_new_tab(self, url):
146+ open_url(url)
110147
111- .. warning :: At the time of writing, the Plyer recipe is not yet
112- ported, and Plyer doesn't support SDL2. These issues will
113- be fixed soon.
148+ import webbrowser
149+ webbrowser.register('android', AndroidBrowser, None, -1)
0 commit comments