Kivy Documentation Release 1.9.2-Dev0
Total Page:16
File Type:pdf, Size:1020Kb
Kivy Documentation Release 1.9.2-dev0 www.kivy.org CONTENTS I User’s Guide3 1 Installation 5 2 Philosophy 25 3 Contributing 27 4 FAQ 39 5 Contact Us 43 II Programming Guide 45 6 Kivy Basics 47 7 Controlling the environment 53 8 Configure Kivy 57 9 Architectural Overview 59 10 Events and Properties 63 11 Input management 71 12 Widgets 77 13 Graphics 97 14 Kv language 99 15 Integrating with other Frameworks 109 16 Best Practices 113 17 Advanced Graphics 115 18 Packaging your application 117 III Tutorials 137 19 Pong Game Tutorial 139 i 20 A Simple Paint App 151 IV API Reference 161 21 Kivy framework 163 22 Adapters 249 23 Core Abstraction 257 24 Kivy module for binary dependencies. 283 25 Effects 285 26 Extension Support 289 27 Garden 293 28 Graphics 295 29 Input management 363 30 Kivy Language 381 31 External libraries 401 32 Modules 403 33 Network support 413 34 Storage 417 35 NO DOCUMENTATION (package kivy.tools) 423 36 Widgets 427 V Appendix 621 37 License 623 Python Module Index 625 ii Welcome to Kivy’s documentation. Kivy is an open source software library for the rapid development of applications equipped with novel user interfaces, such as multi-touch apps. We recommend that you get started with Getting Started. Then head over to the Programming Guide. We also have Create an application if you are impatient. You are probably wondering why you should be interested in using Kivy. There is a document outlining our Philosophy that we encourage you to read, and a detailed Architectural Overview. If you want to contribute to Kivy, make sure to read Contributing. If your concern isn’t addressed in the documentation, feel free to Contact Us. 1 2 Part I USER’S GUIDE This part of the documentation explains the basic ideas behind Kivy’s design and why you’d want to use it. It goes on with a discussion of the architecture and shows you how to create stunning applications in a short time using the framework. 3 4 CHAPTER ONE INSTALLATION We try not to reinvent the wheel, but to bring something innovative to the market. As a consequence, we’re focused on our own code and use pre-existing, high quality third-party libraries where possible. To support the full, rich set of features that Kivy offers, several other libraries are required. If you do not use a specific feature (e.g. video playback), you don’t need the corresponding dependency. That said, there is one dependency that Kivy does require: Cython. This version of Kivy requires at least Cython version 0.20, and has been tested through 0.23. Later versions may work, but as they have not been tested there is no guarantee. In addition, you need a Python 2.x (2.7 <= x < 3.0) or 3.x (3.3 <= x) interpreter. If you want to enable features like windowing (i.e. open a Window), audio/video playback or spelling correction, additional dependencies must be available. For these, we recommend SDL2, Gstreamer 1.x and PyEnchant, re- spectively. Other optional libraries (mutually independent) are: • OpenCV 2.0 – Camera input. • Pillow – Image and text display. • PyEnchant – Spelling correction. That said, DON’T PANIC! We don’t expect you to install all those things on your own. Instead, we have created nice portable packages that you can use directly, and they already contain the necessary packages for your platform. We just want you to know that there are alternatives to the defaults and give you an overview of the things Kivy uses internally. 1.1 Stable Version The latest stable version can be found on Kivy’s website at http://kivy.org/#download. Please refer to the installation instructions for your specific platform: 1.1.1 Installation on Windows Beginning with 1.9.1 we provide binary wheels for Kivy and all its dependencies to be used with an existing Python installation. See Installation. We also provide nightly wheels generated using Kivy master. See Nightly wheel installation. See also Upgrading from a previous Kivy dist. If installing kivy to an alternate location and not to site-packages, please see Installing Kivy to an alternate location. 5 Warning: Python 3.5 is currently not supported on Windows due to issues with MinGW and Python 3.5. Support is not expected for some time. See here for details. If required, 3.5 MSVC builds should be posssible, but have not been attempted, please enquire or let us know if you’ve compiled with MSVC. To use Kivy you need Python. Multiple versions of Python can be installed side by side, but Kivy needs to be installed for each Python version that you want to use Kivy. Installation Now that python is installed, open the Command line and make sure python is available by typing python --version. Then, do the following to install. 1. Ensure you have the latest pip and wheel: python-m pip install--upgrade pip wheel setuptools 2. Install the dependencies (skip gstreamer (~90MB) if not needed, see Kivy’s dependencies): python-m pip install docutils pygments pypiwin32 kivy.deps.sdl2 kivy.deps.glew python-m pip install kivy.deps.gstreamer--extra-index-url https ://kivy.org/downloads/packages/simple/ 3. Install kivy: python-m pip install kivy That’s it. You should now be able to import kivy in python. Note: If you encounter any permission denied errors, try opening the Command prompt as adminis- trator and trying again. Nightly wheel installation Warning: Using the latest development version can be risky and you might encounter issues during development. If you encounter any bugs, please report them. Snapshot wheels of current Kivy master are created every night. They can be found here. To use them, instead of doing python -m pip install kivy we’ll install one of these wheels as follows. • Python 2.7, 32bit • Python 3.4, 32bit • Python 2.7, 64bit • Python 3.4, 64bit 1. Perform steps 1 and 2 of the above Installation section. 2. Download the appropriate wheel for your system. 3. Rename the wheel to remove the version tag, e.g. Kivy-1.9.1.dev0_30112015_gitc68b630-cp27-none-win32.whl should be renamed to Kivy-1.9.1.dev0-cp27-none-win32.whl. 4. Install it with python -m pip install wheel-name where wheel-name is the name of the renamed file. 6 Kivy’s dependencies We offer wheels for Kivy and its dependencies separately so only desired dependencies need be in- stalled. The dependencies are offered as namespace packages of Kivy.deps, e.g. kivy.deps.sdl2. Currently on Windows, we provide the following dependency wheels: gstreamer for audio and video and glew and sdl2 for graphics and control. gstreamer is an optional dependency which only needs to be installed if video display or audio is desired. What are wheels, pip and wheel In Python, packages such as Kivy can be installed with the python package manager, pip. Some pack- ages such as Kivy require additional steps, such as compilation, when installing using the Kivy source code with pip. Wheels (with a .whl extension) are pre-built distributions of a package that has already been compiled and do not require additional steps to install. When hosted on pypi one installs a wheel using pip, e.g. python -m pip install kivy. When downloading and installing a wheel directly, python -m pip install wheel_file_name is used, such as: python-m pip installC :\Kivy-1.9.1.dev-cp27-none-win_amd64.whl Command line Know your command line. To execute any of the pip or wheel commands, one needs a command line tool with python on the path. The default command line on Windows is CMD, and the quickest way to open it is to press Win+R on your keyboard, type cmd in the window that opens, and then press enter. Alternate linux style command shells that we reccomend is Git for Windows which offers a bash com- mand line as well as git. Note, CMD can still be used even if bash is installed. Walking the path! To add your python to the path, simply open your command line and then us the cd command to change the current directory to where python is installed, e.g. cd C:\Python27. Alternatively if you only have one python version installed, permanently add the python directory to the path for CMD for bash. Use development Kivy Warning: Using the latest development version can be risky and you might encounter issues during development. If you encounter any bugs, please report them. To compile and install kivy using the kivy source code or to use kivy with git rather than a wheel there are some additional steps: 1. Both the python and the Python\Scripts directories must be on the path They must be on the path every time you recompile kivy. 2. Ensure you have the latest pip and wheel with: python-m pip install--upgrade pip wheel setuptools 3. Create the python\Lib\distutils\distutils.cfg file and add the two lines: [build] compiler= mingw32 4. Install MinGW with: 7 python-m pip install-i https ://pypi.anaconda.org/carlkl/simple mingwpy 5. Set the environment variables. On windows do: set USE_SDL2=1 set USE_GSTREAMER=1 In bash do: export USE_SDL2=1 export USE_GSTREAMER=1 These variables must be set everytime you recompile kivy. 6. Install the other dependencies as well as their dev versions (you can skip gstreamer and gstreamer_dev if you aren’t going to use video/audio): python-m pip install cython docutils pygments pypiwin32 kivy.deps.sdl2\ kivy.deps.glew kivy.deps.gstreamer kivy.deps.glew_dev kivy.deps.sdl2_dev\ kivy.deps.gstreamer_dev--extra-index-url https ://kivy.org/downloads/packages/simple/ 7.