Skip to content

Commit ec65a95

Browse files
titotito
committed
Merge branch 'master' of github.com:kivy/python-for-android
2 parents fd18902 + 7497d76 commit ec65a95

File tree

10 files changed

+636
-286
lines changed

10 files changed

+636
-286
lines changed

‎docs/source/android.rst

Lines changed: 113 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,16 @@ Example
1919
How it's working
2020
----------------
2121

22-
The whole Android API is accessible in Java. Their is no native or extensible way to access it from Python. The schema for accessing to their API is:
22+
The whole Android API is accessible in Java. Their is no native or extensible way to access it from Python. The schema for accessing to their API is::
2323

2424
[1] Cython -> [2] C JNI -> [3] Java
2525

26-
#. The ``android.pyx`` is written in Cython: a language with typed informations, very close to Python, that generate Python extension. It's easier to write in Cython than CPython, and it's linked directly to the part 2.
27-
#. The second part define simple c methods that access to Java interfaces through JNI in the file ``android_jni.c``.
26+
#. ``android.pyx`` is written in `Cython <http://cython.org/>`_: a language
27+
with typed informations, very close to Python, that generate Python
28+
extension. It's easier to write in Cython than CPython, and it's linked
29+
directly to the part 2.
30+
#. ``android_jni.c`` is defining simple c methods that access to Java
31+
interfaces using JNI layer.
2832
#. The last part contain the Java code that will be called from the JNI stuff.
2933

3034
All the source code is available at:
@@ -35,4 +39,109 @@ All the source code is available at:
3539
API
3640
---
3741

38-
TODO
42+
android
43+
~~~~~~~
44+
45+
.. module:: android
46+
47+
.. function:: check_pause()
48+
49+
This should be called on a regular basis to check to see if Android
50+
expects the game to pause. If it return true, the game should
51+
call :func:`android.wait_for_resume()`, after persisting its state
52+
as necessary.
53+
54+
.. function:: wait_for_resume()
55+
56+
This function should be called after :func:`android.check_pause()`
57+
returns true. It does not return until Android has resumed from
58+
the pause. While in this function, Android may kill a game
59+
without further notice.
60+
61+
.. function:: map_key(keycode, keysym)
62+
63+
This maps between an android keycode and a python keysym. The android
64+
keycodes are available as constants in the android module.
65+
66+
.. function:: vibrate(s)
67+
68+
Causes the phone to vibrate for `s` seconds. This requires that your
69+
application have the VIBRATE permission.
70+
71+
.. function:: accelerometer_enable(enable)
72+
73+
Enables (if `enable` is true) or disables the device's accelerometer.
74+
75+
.. function:: accelerometer_reading()
76+
77+
Returns an (x, y, z) tuple of floats that gives the accelerometer
78+
reading, in meters per second squared. See `this page
79+
<http://developer.android.com/reference/android/hardware/SensorEvent.html>`_
80+
for a description of the coordinate system. The accelerometer must
81+
be enabled before this function is called. If the tuple contains
82+
three zero values, the accelerometer is not enabled, not available,
83+
defective, has not returned a reading, or the device is in
84+
free-fall.
85+
86+
.. function:: get_dpi()
87+
88+
Returns the screen density in dots per inch.
89+
90+
.. function:: show_keyboard()
91+
92+
Shows the soft keyboard.
93+
94+
.. function:: hide_keyboard()
95+
96+
Hides the soft keyboard.
97+
98+
android_mixer
99+
~~~~~~~~~~~~~
100+
101+
.. module:: android_mixer
102+
103+
The android_mixer module contains a subset of the functionality in found
104+
in the `pygame.mixer <http://www.pygame.org/docs/ref/mixer.html>`_ module. It's
105+
intended to be imported as an alternative to pygame.mixer, using code like: ::
106+
107+
try:
108+
import pygame.mixer as mixer
109+
except ImportError:
110+
import android_mixer as mixer
111+
112+
Note that if you're using `kivy.core.audio
113+
<http://kivy.org/docs/api-kivy.core.audio.html>`_ module, you don't have to do
114+
anything, all is automatic.
115+
116+
The android_mixer module is a wrapper around the Android MediaPlayer
117+
class. This allows it to take advantage of any hardware acceleration
118+
present, and also eliminates the need to ship codecs as part of an
119+
application.
120+
121+
It has several differences from the pygame mixer:
122+
123+
* The init and pre_init methods work, but are ignored - Android chooses
124+
appropriate setting automatically.
125+
126+
* Only filenames and true file objects can be used - file-like objects
127+
will probably not work.
128+
129+
* Fadeout does not work - it causes a stop to occur.
130+
131+
* Looping is all or nothing, there's no way to choose the number of
132+
loops that occur. For looping to work, the
133+
:func:`android_mixer.periodic` function should be called on a
134+
regular basis.
135+
136+
* Volume control is ignored.
137+
138+
* End events are not implemented.
139+
140+
* The mixer.music object is a class (with static methods on it),
141+
rather than a module. Calling methods like :func:`mixer.music.play`
142+
should work.
143+
144+
.. note::
145+
146+
The android_mixer module hasn't been tested much, and so bugs may be
147+
present.

‎docs/source/helloworld.rst

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
Hello world example
2+
===================
3+
4+
If you don't know how to start with Python for Android, here is a simple
5+
tutorial for creating an UI using `Kivy <http://kivy.org/>`_, and make an APK
6+
with this project.
7+
8+
.. note::
9+
10+
Don't forget that Python for android is not Kivy only, and you might want
11+
to use other toolkit libraries. When other toolkits will be available, this
12+
documentation will be enhanced.
13+
14+
Let's create a simple Hello world application, with one Label and one Button.
15+
16+
#. Ensure you've correctly installed and configured the project as said in the
17+
:doc:`prerequisites`
18+
19+
#. Create a directory named ``helloworld``::
20+
21+
mkdir helloworld
22+
cd helloworld
23+
24+
#. Create a file named ``main.py``, with this content::
25+
26+
import kivy
27+
kivy.require('1.0.9')
28+
from kivy.lang import Builder
29+
from kivy.uix.gridlayout import GridLayout
30+
from kivy.properties import NumericProperty
31+
from kivy.app import App
32+
33+
Builder.load_string('''
34+
<HelloWorldScreen>:
35+
cols: 1
36+
Label:
37+
text: 'Welcome to the Hello world'
38+
Button:
39+
text: 'Click me! %d' % root.counter
40+
on_release: root.my_callback()
41+
''')
42+
43+
class HelloWorldScreen(GridLayout):
44+
counter = NumericProperty(0)
45+
def my_callback(self):
46+
print 'The button have been pushed'
47+
self.counter += 1
48+
49+
class HelloWorldApp(App):
50+
def build(self):
51+
return HelloWorldScreen()
52+
53+
if __name__ == '__main__':
54+
HelloWorldApp().run()
55+
56+
#. Go to the ``python-for-android`` directory
57+
58+
#. Create a distribute with kivy::
59+
60+
./distribute.sh -m kivy -d 'dist-kivy'
61+
62+
#. Go to the newly created ``dist-kivy`` distribution::
63+
64+
cd dist/dist-kivy
65+
66+
#. Plug your android device, and ensure you can install development application
67+
68+
#. Build your hello world application in debug mode::
69+
70+
./build.py --package org.hello.world --name "Hello world" \
71+
--version 1.0 --dir /PATH/TO/helloworld debug installd
72+
73+
#. Take your device, and start the application!
74+
75+
#. If it's goes wrong, open the logcat by doing::
76+
77+
adb logcat
78+
79+
The final debug APK will be located in ``bin/hello-world-1.0-debug.apk``.
80+
81+
If you want to release your application instead of just making a debug APK, you must:
82+
83+
#. Generate a non-signed APK::
84+
85+
./build.py --package org.hello.world --name "Hello world" \
86+
--version 1.0 --dir /PATH/TO/helloworld release
87+
88+
#. Continue by reading http://developer.android.com/guide/publishing/app-signing.html
89+
90+
91+
.. seealso::
92+
93+
`Kivy demos <https://github.com/kivy/kivy/tree/master/examples/demo>`_
94+
You can use them for creating APK too.
95+

‎docs/source/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ your application.
1919
introduction.rst
2020
prerequisites.rst
2121
usage.rst
22+
helloworld.rst
2223
howitworks.rst
2324
customize.rst
2425
recipes.rst

‎docs/source/prerequisites.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,4 +47,7 @@ After installing them, export both installation path, NDK version and API to use
4747
export ANDROIDNDKVER=r7
4848
export ANDROIDAPI=14
4949

50+
Also, you must configure you're PATH to add the ``android`` binary::
51+
52+
export PATH=/path/to/android-sdk-linux/tools:$PATH
5053

‎docs/source/related.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
Related project
22
===============
33

4-
- SL4A: http://code.google.com/p/android-scripting/
5-
- PGS4A: http://pygame.renpy.org/
4+
- PGS4A: http://pygame.renpy.org/ (thanks to Renpy to make it possible)
65
- Android scripting: http://code.google.com/p/android-scripting/
76
- Python on a chip: http://code.google.com/p/python-on-a-chip/
87

0 commit comments

Comments
 (0)