diff --git a/doc/source/index.rst b/doc/source/index.rst index cee0d5ad4c..16d6162dc3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -38,7 +38,6 @@ Contents troubleshooting docker contribute - old_toolchain/index.rst Indices and tables diff --git a/doc/source/old_toolchain/Screenshot_Kivy_Kompass.png b/doc/source/old_toolchain/Screenshot_Kivy_Kompass.png deleted file mode 100644 index 828ce41952..0000000000 Binary files a/doc/source/old_toolchain/Screenshot_Kivy_Kompass.png and /dev/null differ diff --git a/doc/source/old_toolchain/_static/.empty b/doc/source/old_toolchain/_static/.empty deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/doc/source/old_toolchain/android.rst b/doc/source/old_toolchain/android.rst deleted file mode 100644 index 5d898749af..0000000000 --- a/doc/source/old_toolchain/android.rst +++ /dev/null @@ -1,369 +0,0 @@ -Python API -========== - -The Python for Android project includes a Python module called -``android`` which consists of multiple parts that are mostly there to -facilitate the use of the Java API. - -This module is not designed to be comprehensive. Most of the Java API -is also accessible with PyJNIus, so if you can't find what you need -here you can try using the Java API directly instead. - - -Android (``android``) ---------------------- - -.. module:: android - -.. function:: check_pause() - - This should be called on a regular basis to check to see if Android - expects the application to pause. If it returns true, the app should call - :func:`android.wait_for_resume()`, after storing its state as necessary. - -.. function:: wait_for_resume() - - This function should be called after :func:`android.check_pause()` and returns - true. It does not return until Android has resumed from the pause. While in - this function, Android may kill the app without further notice. - -.. function:: map_key(keycode, keysym) - - This maps an android keycode to a python keysym. The android - keycodes are available as constants in the android module. - - -Activity (``android.activity``) -------------------------------- - -.. module:: android.activity - -The default PythonActivity has a observer pattern for `onActivityResult `_ and `onNewIntent `_. - -.. function:: bind(eventname=callback, ...) - - This allows you to bind a callback to an Android event: - - ``on_new_intent`` is the event associated to the onNewIntent java call - - ``on_activity_result`` is the event associated to the onActivityResult java call - - .. warning:: - - This method is not thread-safe. Call it in the mainthread of your app. (tips: use kivy.clock.mainthread decorator) - -.. function:: unbind(eventname=callback, ...) - - Unregister a previously registered callback with :func:`bind`. - -Example:: - - # This example is a snippet from an NFC p2p app implemented with Kivy. - - from android import activity - - def on_new_intent(self, intent): - if intent.getAction() != NfcAdapter.ACTION_NDEF_DISCOVERED: - return - rawmsgs = intent.getParcelableArrayExtra(NfcAdapter.EXTRA_NDEF_MESSAGES) - if not rawmsgs: - return - for message in rawmsgs: - message = cast(NdefMessage, message) - payload = message.getRecords()[0].getPayload() - print 'payload: {}'.format(''.join(map(chr, payload))) - - def nfc_enable(self): - activity.bind(on_new_intent=self.on_new_intent) - # ... - - def nfc_disable(self): - activity.unbind(on_new_intent=self.on_new_intent) - # ... - - -Billing (``android.billing``) ------------------------------ - -.. module:: android.billing - -This billing module gives an access to the `In-App Billing `_: - -#. `Setup a test account `_, and get your Public Key -#. Export your public key:: - - export BILLING_PUBKEY="Your public key here" - -#. `Setup some In-App product `_ to buy. Let's say you've created a product with the id "org.kivy.gopremium" - -#. In your application, you can use the ``billing`` module like this:: - - - from android.billing import BillingService - from kivy.clock import Clock - - class MyBillingService(object): - - def __init__(self): - super(MyBillingService, self).__init__() - - # Start the billing service, and attach our callback - self.service = BillingService(billing_callback) - - # Start a clock to check billing service message every second - Clock.schedule_interval(self.service.check, 1) - - def billing_callback(self, action, *largs): - '''Callback that will receive all the events from the Billing service - ''' - if action == BillingService.BILLING_ACTION_ITEMSCHANGED: - items = largs[0] - if 'org.kivy.gopremium' in items: - print "Congratulations, you have a premium acess" - else: - print "Unfortunately, you don't have premium access" - - def buy(self, sku): - # Method to buy something. - self.service.buy(sku) - - def get_purchased_items(self): - # Return all the items purchased - return self.service.get_purchased_items() - -#. To initiate an in-app purchase, just call the ``buy()`` method:: - - # Note: start the service at the start, and never twice! - bs = MyBillingService() - bs.buy('org.kivy.gopremium') - - # Later, when you get the notification that items have been changed, you - # can still check all the items you bought: - print bs.get_purchased_items() - {'org.kivy.gopremium': {'qt: 1}} - -#. You'll receive all the notifications about the billing process in the callback. - -#. Last step, create your application with ``--with-billing $BILLING_PUBKEY``:: - - ./build.py ... --with-billing $BILLING_PUBKEY - - -Broadcast (``android.broadcast``) ---------------------------------- - -.. module:: android.broadcast - -Implementation of the android `BroadcastReceiver -`_. -You can specify the callback that will receive the broadcast event, and actions -or categories filters. - -.. class:: BroadcastReceiver - - .. warning:: - - The callback will be called in another thread than the main thread. In - that thread, be careful not to access 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() - - -Mixer (``android.mixer``) -------------------------- - -.. module:: android.mixer - -The `android.mixer` module contains a subset of the functionality in found -in the `pygame.mixer `_ module. It's -intended to be imported as an alternative to pygame.mixer, using code like: :: - - try: - import pygame.mixer as mixer - except ImportError: - import android.mixer as mixer - -Note that if you're using the `kivy.core.audio -`_ module, you don't have to do -anything, it is all automatic. - -The `android.mixer` module is a wrapper around the Android MediaPlayer -class. This allows it to take advantage of any hardware acceleration -present, and also eliminates the need to ship codecs as part of an -application. - -It has several differences with the pygame mixer: - -* The init() and pre_init() methods work, but are ignored - Android chooses - appropriate settings automatically. - -* Only filenames and true file objects can be used - file-like objects - will probably not work. - -* Fadeout does not work - it causes a stop to occur. - -* Looping is all or nothing, there is no way to choose the number of - loops that occur. For looping to work, the - :func:`android.mixer.periodic` function should be called on a - regular basis. - -* Volume control is ignored. - -* End events are not implemented. - -* The mixer.music object is a class (with static methods on it), - rather than a module. Calling methods like :func:`mixer.music.play` - should work. - - -Runnable (``android.runnable``) -------------------------------- - -.. module:: android.runnable - -:class:`Runnable` is a wrapper around the Java `Runnable -`_ class. This -class can be used to schedule a call of a Python function into the -`PythonActivity` thread. - -Example:: - - from android.runnable import Runnable - - def helloworld(arg): - print 'Called from PythonActivity with arg:', arg - - Runnable(helloworld)('hello') - -Or use our decorator:: - - from android.runnable import run_on_ui_thread - - @run_on_ui_thread - def helloworld(arg): - print 'Called from PythonActivity with arg:', arg - - helloworld('arg1') - - -This can be used to prevent errors like: - - - W/System.err( 9514): java.lang.RuntimeException: Can't create handler - inside thread that has not called Looper.prepare() - - NullPointerException in ActivityThread.currentActivityThread() - -.. warning:: - - Because the python function is called from the PythonActivity thread, you - need to be careful about your own calls. - - - -Service (``android.service``) ------------------------------ - -Services of an application are controlled through the class :class:`AndroidService`. - -.. module:: android.service - -.. class:: AndroidService(title, description) - - Run ``service/main.py`` from the application directory as a service. - - :param title: Notification title, default to 'Python service' - :param description: Notification text, default to 'Kivy Python service started' - :type title: str - :type description: str - - .. method:: start(arg) - - Start the service. - - :param arg: Argument to pass to a service, through the environment variable - ``PYTHON_SERVICE_ARGUMENT``. Defaults to '' - :type arg: str - - .. method:: stop() - - Stop the service. - -Application activity part example, ``main.py``: - -.. code-block:: python - - from android import AndroidService - - ... - - class ServiceExample(App): - - ... - - def start_service(self): - self.service = AndroidService('Sevice example', 'service is running') - self.service.start('Hello From Service') - - def stop_service(self): - self.service.stop() - -Application service part example, ``service/main.py``: - -.. code-block:: python - - import os - import time - - # get the argument passed - arg = os.getenv('PYTHON_SERVICE_ARGUMENT') - - while True: - # this will print 'Hello From Service' continually, even when the application is switched - print arg - time.sleep(1) - diff --git a/doc/source/old_toolchain/conf.py b/doc/source/old_toolchain/conf.py deleted file mode 100644 index 02498acb27..0000000000 --- a/doc/source/old_toolchain/conf.py +++ /dev/null @@ -1,242 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Python for Android documentation build configuration file, created by -# sphinx-quickstart on Wed Jan 11 02:31:33 2012. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Python for Android' -copyright = u'2012/2013, Kivy organisation' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '1.2' -# The full version, including alpha/beta/rc tags. -release = '1.2' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = [] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'default' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'PythonForAndroiddoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'PythonForAndroid.tex', u'Python for Android Documentation', - u'Mathieu Virbel', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'pythonforandroid', u'Python for Android Documentation', - [u'Mathieu Virbel'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'PythonForAndroid', u'Python for Android Documentation', - u'Mathieu Virbel', 'PythonForAndroid', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' diff --git a/doc/source/old_toolchain/contribute.rst b/doc/source/old_toolchain/contribute.rst deleted file mode 100644 index dcc0fbe7c6..0000000000 --- a/doc/source/old_toolchain/contribute.rst +++ /dev/null @@ -1,105 +0,0 @@ -Contribute -========== - -Extending Python for android native support -------------------------------------------- - -So, you want to get into python-for-android and extend what's available -to Python on Android ? - -Turns out it's not very complicated, here is a little introduction on how to go -about it. Without Pyjnius, the schema to access the Java API from Cython is:: - - [1] Cython -> [2] C JNI -> [3] Java - -Think about acceleration sensors: you want to get the acceleration -values in Python, but nothing is available natively. Lukcily you have -a Java API for that : the Google API is available here -http://developer.android.com/reference/android/hardware/Sensor.html - -You can't use it directly, you need to do your own API to use it in python, -this is done in 3 steps - -Step 1: write the java code to create very simple functions to use -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -like : accelerometer Enable/Reading -In our project, this is done in the Hardware.java: -https://github.com/kivy/python-for-android/blob/master/src/src/org/renpy/android/Hardware.java -you can see how it's implemented - -Step 2 : write a jni wrapper -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is a C file to be able to invoke/call Java functions from C, in our case, -step 2 (and 3) are done in the android python module. The JNI part is done in -the android_jni.c: -https://github.com/kivy/python-for-android/blob/master/recipes/android/src/android_jni.c - -Step 3 : you have the java part, that you can call from the C -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can now do the Python extension around it, all the android python part is -done in -https://github.com/kivy/python-for-android/blob/master/recipes/android/src/android.pyx - -→ [python] android.accelerometer_reading ⇒ [C] android_accelerometer_reading -⇒ [Java] Hardware.accelerometer_reading() - -The jni part is really a C api to call java methods. a little bit hard to get -it with the syntax, but working with current example should be ok - -Example with bluetooth -~~~~~~~~~~~~~~~~~~~~~~ -Start directly from a fork of https://github.com/kivy/python-for-android - -The first step is to identify where and how they are doing it in sl4a, it's -really easy, because everything is already done as a client/server -client/consumer approach, for bluetooth, they have a "Bluetooth facade" in -java. - -http://code.google.com/p/android-scripting/source/browse/android/BluetoothFacade/src/com/googlecode/android_scripting/facade/BluetoothFacade.java - -You can learn from it, and see how is it's can be used as is, or if you can -simplify / remove stuff you don't want. - -From this point, create a bluetooth file in -python-for-android/tree/master/src/src/org/renpy/android in Java. - -Do a good API (enough simple to be able to write the jni in a very easy manner, -like, don't pass any custom java object in argument). - -Then write the JNI, and then the python part. - -3 steps, once you get it, the real difficult part is to write the java part :) - -Jni gottchas -~~~~~~~~~~~~ - -- package must be org.renpy.android, don't change it. - - -Create your own recipes ------------------------ - -A recipe is a script that contains the "definition" of a module to compile. -The directory layout of a recipe for a is something like:: - - python-for-android/recipes//recipe.sh - python-for-android/recipes//patches/ - python-for-android/recipes//patches/fix-path.patch - -When building, all the recipe builds must go to:: - - python-for-android/build// - -For example, if you want to create a recipe for sdl, do:: - - cd python-for-android/recipes - mkdir sdl - cp recipe.sh.tmpl sdl/recipe.sh - sed -i 's#XXX#sdl#' sdl/recipe.sh - -Then, edit the sdl/recipe.sh to adjust other information (version, url) and -complete the build function. - diff --git a/doc/source/old_toolchain/customize.rst b/doc/source/old_toolchain/customize.rst deleted file mode 100644 index 5b9d954d27..0000000000 --- a/doc/source/old_toolchain/customize.rst +++ /dev/null @@ -1,30 +0,0 @@ -Customize your distribution ---------------------------- - -The basic layout of a distribution is:: - - AndroidManifest.xml - (*) android manifest (generated from templates) - assets/ - private.mp3 - (*) fake package that will contain all the python installation - public.mp3 - (*) fake package that will contain your application - bin/ - contain all the apk generated from build.py - blacklist.txt - list of file patterns to not include in the APK - buildlib/ - internals libraries for build.py - build.py - build script to use for packaging your application - build.xml - (*) build settings (generated from templates) - default.properties - settings generated from your distribute.sh - libs/ - contain all the compiled libraries - local.properties - settings generated from your distribute.sh - private/ - private directory containing all the python files - lib/ this is where you can remove or add python libs. - python2.7/ by default, some modules are already removed (tests, idlelib, ...) - project.properties - settings generated from your distribute.sh - python-install/ - the whole python installation, generated from distribute.sh - not included in the final package. - res/ - (*) android resource (generated from build.py) - src/ - Java bootstrap - templates/ - Templates used by build.py - - (*): Theses files are automatically generated from build.py, don't change them directly ! - - diff --git a/doc/source/old_toolchain/example_compass.rst b/doc/source/old_toolchain/example_compass.rst deleted file mode 100644 index bff430eafe..0000000000 --- a/doc/source/old_toolchain/example_compass.rst +++ /dev/null @@ -1,61 +0,0 @@ -Compass -------- - -The following example is an extract from the Compass app as provided in the Kivy -`examples/android/compass `__ -folder: - -.. code-block:: python - - # ... imports - Hardware = autoclass('org.renpy.android.Hardware') - - class CompassApp(App): - - needle_angle = NumericProperty(0) - - def build(self): - self._anim = None - Hardware.magneticFieldSensorEnable(True) - Clock.schedule_interval(self.update_compass, 1 / 10.) - - def update_compass(self, *args): - # read the magnetic sensor from the Hardware class - (x, y, z) = Hardware.magneticFieldSensorReading() - - # calculate the angle - needle_angle = Vector(x , y).angle((0, 1)) + 90. - - # animate the needle - if self._anim: - self._anim.stop(self) - self._anim = Animation(needle_angle=needle_angle, d=.2, t='out_quad') - self._anim.start(self) - - def on_pause(self): - # when you are going on pause, don't forget to stop the sensor - Hardware.magneticFieldSensorEnable(False) - return True - - def on_resume(self): - # reactivate the sensor when you are back to the app - Hardware.magneticFieldSensorEnable(True) - - if __name__ == '__main__': - CompassApp().run() - - -If you compile this app, you will get an APK which outputs the following -screen: - -.. figure:: Screenshot_Kivy_Kompass.png - :width: 100% - :scale: 60% - :figwidth: 80% - :alt: Screenshot Kivy Compass - - Screenshot of the Kivy Compass App - (Source of the Compass Windrose: `Wikipedia `__) - - - diff --git a/doc/source/old_toolchain/example_helloworld.rst b/doc/source/old_toolchain/example_helloworld.rst deleted file mode 100644 index dab760ad4b..0000000000 --- a/doc/source/old_toolchain/example_helloworld.rst +++ /dev/null @@ -1,96 +0,0 @@ -Hello world ------------ - -If you don't know how to start with Python for Android, here is a simple -tutorial for creating an UI using `Kivy `_, and make an APK -with this project. - -.. note:: - - Don't forget that Python for Android is not Kivy only, and you - might want to use other toolkit libraries. When other toolkits - will be available, this documentation will be enhanced. - -Let's create a simple Hello world application, with one Label and one Button. - -#. Ensure you've correctly installed and configured the project as said in the - :doc:`prerequisites` - -#. Create a directory named ``helloworld``:: - - mkdir helloworld - cd helloworld - -#. Create a file named ``main.py``, with this content:: - - import kivy - kivy.require('1.0.9') - from kivy.lang import Builder - from kivy.uix.gridlayout import GridLayout - from kivy.properties import NumericProperty - from kivy.app import App - - Builder.load_string(''' - : - cols: 1 - Label: - text: 'Welcome to the Hello world' - Button: - text: 'Click me! %d' % root.counter - on_release: root.my_callback() - ''') - - class HelloWorldScreen(GridLayout): - counter = NumericProperty(0) - def my_callback(self): - print 'The button has been pushed' - self.counter += 1 - - class HelloWorldApp(App): - def build(self): - return HelloWorldScreen() - - if __name__ == '__main__': - HelloWorldApp().run() - -#. Go to the ``python-for-android`` directory - -#. Create a distribution with kivy:: - - ./distribute.sh -m kivy - -#. Go to the newly created ``default`` distribution:: - - cd dist/default - -#. Plug your android device, and ensure you can install development - application - -#. Build your hello world application in debug mode:: - - ./build.py --package org.hello.world --name "Hello world" \ - --version 1.0 --dir /PATH/TO/helloworld debug installd - -#. Take your device, and start the application! - -#. If something goes wrong, open the logcat by doing:: - - adb logcat - -The final debug APK will be located in ``bin/hello-world-1.0-debug.apk``. - -If you want to release your application instead of just making a debug APK, you must: - -#. Generate a non-signed APK:: - - ./build.py --package org.hello.world --name "Hello world" \ - --version 1.0 --dir /PATH/TO/helloworld release - -#. Continue by reading http://developer.android.com/guide/publishing/app-signing.html - - -.. seealso:: - - `Kivy demos `_ - You can use them for creating APK too. - diff --git a/doc/source/old_toolchain/examples.rst b/doc/source/old_toolchain/examples.rst deleted file mode 100644 index 4d7408fa0c..0000000000 --- a/doc/source/old_toolchain/examples.rst +++ /dev/null @@ -1,21 +0,0 @@ -Examples -======== - -Prebuilt VirtualBox -------------------- - -A good starting point to build an APK are prebuilt VirtualBox images, -where the Android NDK, the Android SDK, and the Kivy -Python-For-Android sources are prebuilt in an VirtualBox image. Please -search the `Download Section `__ for such -an image. You will also need to create a device filter for the Android -USB device using the VirtualBox OS settings. - -.. include:: example_helloworld.rst -.. include:: example_compass.rst - -.. toctree:: - :hidden: - - example_helloworld - example_compass diff --git a/doc/source/old_toolchain/faq.rst b/doc/source/old_toolchain/faq.rst deleted file mode 100644 index 22ffe11512..0000000000 --- a/doc/source/old_toolchain/faq.rst +++ /dev/null @@ -1,41 +0,0 @@ -FAQ -=== - -arm-linux-androideabi-gcc: Internal error: Killed (program cc1) ---------------------------------------------------------------- - -This could happen if you are not using a validated SDK/NDK with Python for -Android. Go to :doc:`prerequisites` to see which one are working. - -_sqlite3.so not found ---------------------- - -We recently fixed sqlite3 compilation. In case of this error, you -must: - -* Install development headers for sqlite3 if they are not already - installed. On Ubuntu: - - apt-get install libsqlite3-dev - -* Compile the distribution with (sqlite3 must be the first argument):: - - ./distribute.sh -m 'sqlite3 kivy' - -* Go into your distribution at `dist/default` -* Edit blacklist.txt, and remove all the lines concerning sqlite3:: - - sqlite3/* - lib-dynload/_sqlite3.so - -Then sqlite3 will be compiled and included in your APK. - -Too many levels of symbolic links ------------------------------------------------------ - -Python for Android does not work within a virtual enviroment. The Python for -Android directory must be outside of the virtual enviroment prior to running - - ./distribute.sh -m "kivy" - -or else you may encounter OSError: [Errno 40] Too many levels of symbolic links. \ No newline at end of file diff --git a/doc/source/old_toolchain/index.rst b/doc/source/old_toolchain/index.rst deleted file mode 100644 index 1b873be657..0000000000 --- a/doc/source/old_toolchain/index.rst +++ /dev/null @@ -1,38 +0,0 @@ - -Old p4a toolchain doc -===================== - -This is the documentation for the old python-for-android toolchain, -using distribute.sh and build.py. This it entirely superseded by the -new toolchain, you do not need to read it unless using this old -method. - -.. warning:: The old toolchain is deprecated and no longer - supported. You should instead use the :doc:`current version - <../quickstart>`. - -Python for android is a project to create your own Python distribution -including the modules you want, and create an apk including python, libs, and -your application. - -- Forum: https://groups.google.com/forum/#!forum/python-android -- Mailing list: python-android@googlegroups.com - -.. toctree:: - :maxdepth: 2 - - toolchain.rst - examples.rst - android.rst - javaapi.rst - contribute.rst - related.rst - faq.rst - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/doc/source/old_toolchain/javaapi.rst b/doc/source/old_toolchain/javaapi.rst deleted file mode 100644 index 73fc888f8e..0000000000 --- a/doc/source/old_toolchain/javaapi.rst +++ /dev/null @@ -1,239 +0,0 @@ -Java API (pyjnius) -================== - -Using `PyJNIus `__ to access the Android API -restricts the usage to a simple call of the **autoclass** constructor function -and a second call to instantiate this class. - -You can access through this method the entire Java Android API, e.g., -the ``DisplayMetrics`` of an Android device could be fetched using the -following piece of code: - -.. code-block:: python - - DisplayMetrics = autoclass('android.util.DisplayMetrics') - metrics = DisplayMetrics() - metrics.setToDefaults() - self.densityDpi = metrics.densityDpi - -You can access all fields and methods as described in the `Java -Android DisplayMetrics API -`__ -as shown here with the method `setToDefaults()` and the field -`densityDpi`. Before you use a view field, you should always call -`setToDefaults` to initiate to the default values of the device. - -Currently only JavaMethod, JavaStaticMethod, JavaField, -JavaStaticField and JavaMultipleMethod are built into PyJNIus, -therefore such constructs like registerListener or something like this -must still be coded in Java. For this the Android module described -below is available to access some of the hardware on Android devices. - -.. module:: org.renpy.android - - -Activity --------- - -If you want the instance of the current Activity, use: - -- :data:`PythonActivity.mActivity` if you are running an application -- :data:`PythonService.mService` if you are running a service - -.. class:: PythonActivity - - .. data:: mInfo - - Instance of an `ApplicationInfo - `_ - - .. data:: mActivity - - Instance of :class:`PythonActivity`. - - .. method:: registerNewIntentListener(NewIntentListener listener) - - Register a new instance of :class:`NewIntentListener` to be called when - `onNewIntent - `_ - is called. - - .. method:: unregisterNewIntentListener(NewIntentListener listener) - - Unregister a previously registered listener from - :meth:`registerNewIntentListener` - - .. method:: registerActivityResultListener(ActivityResultListener listener) - - Register a new instance of :class:`ActivityResultListener` to be called - when `onActivityResult - `_ is called. - - .. method:: unregisterActivityResultListener(ActivityResultListener listener) - - Unregister a previously registered listener from - :meth:`PythonActivity.registerActivityResultListener` - -.. class:: PythonActivity_ActivityResultListener - - .. note:: - - This class is a subclass of PythonActivity, so the notation will be - ``PythonActivity$ActivityResultListener`` - - Listener interface for onActivityResult. You need to implementing it, - create an instance and use it with :meth:`PythonActivity.registerActivityResultListener`. - - .. method:: onActivityResult(int requestCode, int resultCode, Intent data) - - Method to implement - -.. class:: PythonActivity_NewIntentListener - - .. note:: - - This class is a subclass of PythonActivity, so the notation will be - ``PythonActivity$NewIntentListener`` - - Listener interface for onNewIntent. You need to implementing it, create - an instance and use it with :meth:`registerNewIntentListener`. - - .. method:: onNewIntent(Intent intent) - - Method to implement - - -Action ------- - -.. class:: Action - - This module is built to deliver data to someone else. - - .. method:: send(mimetype, filename, subject, text, chooser_title) - - Deliver data to someone else. This method is a wrapper around `ACTION_SEND - `_ - - :Parameters: - `mimetype`: str - Must be a valid mimetype, that represent the content to sent. - `filename`: str, default to None - (optional) Name of the file to attach. Must be a absolute path. - `subject`: str, default to None - (optional) Default subject - `text`: str, default to None - (optional) Content to send. - `chooser_title`: str, default to None - (optional) Title of the android chooser window, default to 'Send email...' - - Sending a simple hello world text:: - - android.action_send('text/plain', text='Hello world', - subject='Test from python') - - Sharing an image file:: - - # let's say you've make an image in /sdcard/image.png - android.action_send('image/png', filename='/sdcard/image.png') - - Sharing an image with a default text too:: - - android.action_send('image/png', filename='/sdcard/image.png', - text='Hi,\n\tThis is my awesome image, what do you think about it ?') - - -Hardware --------- - -.. class:: Hardware - - This module is built for accessing hardware devices of an Android device. - All the methods are static and public, you don't need an instance. - - - .. method:: vibrate(s) - - Causes the phone to vibrate for `s` seconds. This requires that your - application have the VIBRATE permission. - - - .. method:: getHardwareSensors() - - Returns a string of all hardware sensors of an Android device where each - line lists the informations about one sensor in the following format: - - Name=name,Vendor=vendor,Version=version,MaximumRange=maximumRange,MinDelay=minDelay,Power=power,Type=type - - For more information about this informations look into the original Java - API for the `Sensors Class - `__ - - .. attribute:: accelerometerSensor - - This variable links to a generic3AxisSensor instance and their functions to - access the accelerometer sensor - - .. attribute:: orientationSensor - - This variable links to a generic3AxisSensor instance and their functions to - access the orientation sensor - - .. attribute:: magenticFieldSensor - - - The following two instance methods of the generic3AxisSensor class should be - used to enable/disable the sensor and to read the sensor - - - .. method:: changeStatus(boolean enable) - - Changes the status of the sensor, the status of the sensor is enabled, - if `enable` is true or disabled, if `enable` is false. - - .. method:: readSensor() - - Returns an (x, y, z) tuple of floats that gives the sensor reading, the - units depend on the sensor as shown on the Java API page for - `SensorEvent - `_. - The sesnor must be enabled before this function is called. If the tuple - contains three zero values, the accelerometer is not enabled, not - available, defective, has not returned a reading, or the device is in - free-fall. - - .. method:: get_dpi() - - Returns the screen density in dots per inch. - - .. method:: show_keyboard() - - Shows the soft keyboard. - - .. method:: hide_keyboard() - - Hides the soft keyboard. - - .. method:: wifi_scanner_enable() - - Enables wifi scanning. - - .. note:: - - ACCESS_WIFI_STATE and CHANGE_WIFI_STATE permissions are required. - - .. method:: wifi_scan() - - Returns a String for each visible WiFi access point - - (SSID, BSSID, SignalLevel) - -Further Modules -~~~~~~~~~~~~~~~ - -Some further modules are currently available but not yet documented. Please -have a look into the code and you are very welcome to contribute to this -documentation. - - diff --git a/doc/source/old_toolchain/prerequisites.rst b/doc/source/old_toolchain/prerequisites.rst deleted file mode 100644 index eb5cd6dcd0..0000000000 --- a/doc/source/old_toolchain/prerequisites.rst +++ /dev/null @@ -1,79 +0,0 @@ -Prerequisites -------------- - -.. note:: There is a VirtualBox Image we provide with the - prerequisites along with the Android SDK and NDK preinstalled to - ease your installation woes. You can download it from `here - `__. - -.. warning:: - - The current version is tested only on Ubuntu oneiric (11.10) and - precise (12.04). If it doesn't work on other platforms, send us a - patch, not a bug report. Python for Android works on Linux and Mac - OS X, not Windows. - -You need the minimal environment for building python. Note that other -libraries might need other tools (cython is used by some recipes, and -ccache to speedup the build):: - - sudo apt-get install build-essential patch git-core ccache ant python-pip python-dev - -If you are on a 64 bit distro, you should install these packages too :: - - sudo apt-get install ia32-libs libc6-dev-i386 - -On debian Squeeze amd64, those packages were found to be necessary :: - - sudo apt-get install lib32stdc++6 lib32z1 - -Ensure you have the latest Cython version:: - - pip install --upgrade cython - -You must have android SDK and NDK. The SDK defines the Android -functions you can use. The NDK is used for compilation. Right now, -it's preferred to use: - -- SDK API 8 or 14 (15 will only work with a newly released NDK) -- NDK r5b or r7 - -You can download them at:: - - http://developer.android.com/sdk/index.html - http://developer.android.com/sdk/ndk/index.html - - -In general, Python for Android currently works with Android 2.3 to L. - -If it's your very first time using the Android SDK, don't forget to -follow the documentation for recommended components at:: - - http://developer.android.com/sdk/installing/adding-packages.html - - You need to download at least one platform into your environment, so - that you will be able to compile your application and set up an Android - Virtual Device (AVD) to run it on (in the emulator). To start with, - just download the latest version of the platform. Later, if you plan to - publish your application, you will want to download other platforms as - well, so that you can test your application on the full range of - Android platform versions that your application supports. - -After installing them, export both installation paths, NDK version, -and API to use:: - - export ANDROIDSDK=/path/to/android-sdk - export ANDROIDNDK=/path/to/android-ndk - export ANDROIDNDKVER=rX - export ANDROIDAPI=X - - # example - export ANDROIDSDK="/home/tito/code/android/android-sdk-linux_86" - export ANDROIDNDK="/home/tito/code/android/android-ndk-r7" - export ANDROIDNDKVER=r7 - export ANDROIDAPI=14 - -Also, you must configure your PATH to add the ``android`` binary:: - - export PATH=$ANDROIDNDK:$ANDROIDSDK/platform-tools:$ANDROIDSDK/tools:$PATH - diff --git a/doc/source/old_toolchain/related.rst b/doc/source/old_toolchain/related.rst deleted file mode 100644 index ea694f619c..0000000000 --- a/doc/source/old_toolchain/related.rst +++ /dev/null @@ -1,7 +0,0 @@ -Related projects -================ - -- PGS4A: http://pygame.renpy.org/ (thanks to Renpy to make it possible) -- Android scripting: http://code.google.com/p/android-scripting/ -- Python on a chip: http://code.google.com/p/python-on-a-chip/ - diff --git a/doc/source/old_toolchain/toolchain.rst b/doc/source/old_toolchain/toolchain.rst deleted file mode 100644 index b301a5a9f5..0000000000 --- a/doc/source/old_toolchain/toolchain.rst +++ /dev/null @@ -1,66 +0,0 @@ -Toolchain -========= - -Introduction ------------- - -In terms of comparaison, you can check how Python for android can be useful -compared to other projects. - -+--------------------+---------------+---------------+----------------+--------------+ -| Project | Native Python | GUI libraries | APK generation | Custom build | -+====================+===============+===============+================+==============+ -| Python for android | Yes | Yes | Yes | Yes | -+--------------------+---------------+---------------+----------------+--------------+ -| PGS4A | Yes | Yes | Yes | No | -+--------------------+---------------+---------------+----------------+--------------+ -| Android scripting | No | No | No | No | -+--------------------+---------------+---------------+----------------+--------------+ -| Python on a chip | No | No | No | No | -+--------------------+---------------+---------------+----------------+--------------+ - -.. note:: - - For the moment, we are shipping only one "java bootstrap" (needed for - decompressing your packaged zip file project, create an OpenGL ES 2.0 - surface, handle touch input and manage an audio thread). - - If you want to use it without kivy module (an opengl es 2.0 ui toolkit), - then you might want a lighter java bootstrap, that we don't have right now. - Help is welcome :) - - So for the moment, Python for Android can only be used with the kivy GUI toolkit: - http://kivy.org/#home - - -How does it work ? ------------------- - -To be able to run Python on android, you need to compile it for android. And -you need to compile all the libraries you want for android too. -Since Python is a language, not a toolkit, you cannot draw any user interface -with it: you need to use a toolkit for it. Kivy can be one of them. - -So for a simple ui project, the first step is to compile Python + Kivy + all -others libraries. Then you'll have what we call a "distribution". -A distribution is composed of: - -- Python -- Python libraries -- All selected libraries (kivy, pygame, pil...) -- A java bootstrap -- A build script - -You'll use the build script for create an "apk": an android package. - - -.. include:: prerequisites.rst -.. include:: usage.rst -.. include:: customize.rst - -.. toctree:: - :hidden: - - prerequisites - usage - customize diff --git a/doc/source/old_toolchain/usage.rst b/doc/source/old_toolchain/usage.rst deleted file mode 100644 index 7d83b23888..0000000000 --- a/doc/source/old_toolchain/usage.rst +++ /dev/null @@ -1,167 +0,0 @@ -Usage ------ - -Step 1: compile the toolchain -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want to compile the toolchain with only the kivy module:: - - ./distribute.sh -m "kivy" - -.. warning:: - Do not run the above command from `within a virtual enviroment <../faq/#too-many-levels-of-symbolic-links>`_. - -After a long time, you'll get a "dist/default" directory containing -all the compiled libraries and a build.py script to package your -application using thoses libraries. - -You can include other modules (or "recipes") to compile using `-m`:: - - ./distribute.sh -m "openssl kivy" - ./distribute.sh -m "pil ffmpeg kivy" - -.. note:: - - Recipes are instructions for compiling Python modules that require C extensions. - The list of recipes we currently have is at: - https://github.com/kivy/python-for-android/tree/master/recipes - -You can also specify a specific version for each package. Please note -that the compilation might **break** if you don't use the default -version. Most recipes have patches to fix Android issues, and might -not apply if you specify a version. We also recommend to clean build -before changing version.:: - - ./distribute.sh -m "openssl kivy==master" - -Python modules that don't need C extensions don't need a recipe and -can be included this way. From python-for-android 1.1 on, you can now -specify pure-python package into the distribution. It will use -virtualenv and pip to install pure-python modules into the -distribution. Please note that the compiler is deactivated, and will -break any module which tries to compile something. If compilation is -needed, write a recipe:: - - ./distribute.sh -m "requests pygments kivy" - -.. note:: - - Recipes download a defined version of their needed package from the - internet, and build from it. If you know what you are doing, and - want to override that, you can export the env variable - `P4A_recipe_name_DIR` and this directory will be copied and used - instead. - -Available options to `distribute.sh`:: - - -d directory Name of the distribution directory - -h Show this help - -l Show a list of available modules - -m 'mod1 mod2' Modules to include - -f Restart from scratch (remove the current build) - -u 'mod1 mod2' Modules to update (if already compiled) - -Step 2: package your application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Go to your custom Python distribution:: - - cd dist/default - -Use the build.py for creating the APK:: - - ./build.py --package org.test.touchtracer --name touchtracer \ - --version 1.0 --dir ~/code/kivy/examples/demo/touchtracer debug - -Then, the Android package (APK) will be generated at: - - bin/touchtracer-1.0-debug.apk - -.. warning:: - - Some files and modules for python are blacklisted by default to - save a few megabytes on the final APK file. In case your - applications doesn't find a standard python module, check the - src/blacklist.txt file, remove the module you need from the list, - and try again. - -Available options to `build.py`:: - - -h, --help show this help message and exit - --package PACKAGE The name of the java package the project will be - packaged under. - --name NAME The human-readable name of the project. - --version VERSION The version number of the project. This should consist - of numbers and dots, and should have the same number - of groups of numbers as previous versions. - --numeric-version NUMERIC_VERSION - The numeric version number of the project. If not - given, this is automatically computed from the - version. - --dir DIR The directory containing public files for the project. - --private PRIVATE The directory containing additional private files for - the project. - --launcher Provide this argument to build a multi-app launcher, - rather than a single app. - --icon-name ICON_NAME - The name of the project's launcher icon. - --orientation ORIENTATION - The orientation that the game will display in. Usually - one of "landscape", "portrait" or "sensor". - --permission PERMISSIONS - The permissions to give this app. - --ignore-path IGNORE_PATH - Ignore path when building the app - --icon ICON A png file to use as the icon for the application. - --presplash PRESPLASH - A jpeg file to use as a screen while the application - is loading. - --install-location INSTALL_LOCATION - The default install location. Should be "auto", - "preferExternal" or "internalOnly". - --compile-pyo Compile all .py files to .pyo, and only distribute the - compiled bytecode. - --intent-filters INTENT_FILTERS - Add intent-filters xml rules to AndroidManifest.xml - --blacklist BLACKLIST - Use a blacklist file to match unwanted file in the - final APK - --sdk SDK_VERSION Android SDK version to use. Default to 8 - --minsdk MIN_SDK_VERSION - Minimum Android SDK version to use. Default to 8 - --window Indicate if the application will be windowed - -Meta-data ---------- - -.. versionadded:: 1.3 - -You can extend the `AndroidManifest.xml` with application meta-data. If you are -using external toolkits like Google Maps, you might want to set your API key in -the meta-data. You could do it like this:: - - ./build.py ... --meta-data com.google.android.maps.v2.API_KEY=YOURAPIKEY - -Some meta-data can be used to interact with the behavior of our internal -component. - -.. list-table:: - :widths: 100 500 - :header-rows: 1 - - * - Token - - Description - * - `surface.transparent` - - If set to 1, the created surface will be transparent (can be used - to add background Android widget in the background, or use accelerated - widgets) - * - `surface.depth` - - Size of the depth component, default to 0. 0 means automatic, but you - can force it to a specific value. Be warned, some old phone might not - support the depth you want. - * - `surface.stencil` - - Size of the stencil component, default to 8. - * - `android.background_color` - - Color (32bits RGBA color), used for the background window. Usually, the - background is covered by the OpenGL Background, unless - `surface.transparent` is set. diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index 8de4471a01..3e8042537a 100644 --- a/doc/source/quickstart.rst +++ b/doc/source/quickstart.rst @@ -282,6 +282,17 @@ include such as:: --android_api 27 --requirements kivy,openssl +Overriding recipes sources +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can override the source of any recipe using the +``$P4A_recipename_DIR`` environment variable. For instance, to test +your own Kivy branch you might set:: + + export P4A_kivy_DIR=/home/username/kivy + +The specified directory will be copied into python-for-android instead +of downloading from the normal url specified in the recipe. Going further ~~~~~~~~~~~~~