Kivy Documentation

1 kivy DocumentationRelease kivy DevelopersMarch 28, 2023 CONTENTSI Getting Started31 Introduction52 Installing Kivy73 A first App154 Properties175 Kv Design Language196 Events217 Non-widget stuff238 Layouts259 Drawing2710 Packaging2911 Diving in31II kivy Project3312 Philosophy3513 Contributing3714 FAQ5315 Contact Us59 III Programming Guide6116 kivy Basics6317 Controlling the environment6918 Configure Kivy7519 Architectural Overview77i20 Events and Properties8121 Input management9122 Widgets9923 Graphics11924 Kv language12125 Integrating with other Frameworks13326 Packaging your application13727 Package licensing155IV Tutorials15928 Pong Game Tutorial16129 A Simple Paint App17530 Crash Course185V API Reference18731 kivy

2 Framework18932 Core Abstraction30733 kivy module for binary Effects35135 Event Manager35736 Garden36137 Graphics36538 Input management46139 kivy Language48740 External libraries51141 Modules51542 Network support52743 Storage53344 Tools53945 Widgets541iiVI Appendix81146 License813 Python Module Index815 Index817iiiivWelcome to kivy s Documentation . kivy is an open source software library for the rapid developmentof applications equipped with novel user interfaces, such as multi-touch recommend that you get started withGetting Started. Then head over to theProgramming Guide. Wealso haveCreate an applicationif you are are probably wondering why you should be interested in using kivy . There is a document outliningourPhilosophythat we encourage you to read, and a detailedArchitectural you want to contribute to kivy , make sure to readContributing.

3 If your concern isn t addressed in thedocumentation, feel free toContact IGETTING STARTED34 CHAPTERONEINTRODUCTIONS tart Developing kivy Apps Right Away!Creating kivy apps is fun and rewarding. This guide should be the perfect starting point to get youon the right track for app development. You will require a basic knowledge of Python to follow you need more background on the Python language, you might be interested in these tutorials: The Official Python Tutorial Learn Python in 10 minutes Learn Python the hard wayWith kivy , you can create apps that run on: Desktop computers: macOS, Linux,*BSD Unix, Windows. iOS devices: iPad, iPhone. Android devices: tablets, phones. Any other touch-enabled professional/homebrew devices supporting TUIO (Tangible User Inter-face Objects).

4 kivy empowers you with the freedom to write your code once and have it run as-is on different this guide to get the tools you need, understand the major concepts and learn best practices. Asthis is an introduction, pointers to more information will be provided at the end of each you proceed through the guide, you will, using kivy : Learn: The basics of programming with the kivy Explore: The kivy framework. Create: A simple cross-platform app. Package: For your choice of , you will learn how toDeployon the device of your section of the guide introduces a new topic, trying to give you enough information to get startedand links to related articles for more in-depth explanations. When you are done with this guide, you llbe able to develop kivy apps and you will know where to look for information for the more challengingstuff your innovative applications will introductions, let s get down to KIVYI nstallation for kivy Read the changelog here.

5 For other kivy versions, select thedocumentation from the dropdown on the top officially supports Python - , ,PyInstallerLinuxpip, PPA *BSD (FreeBSD,..)pip RPipip Androidpython-for-androidpython-for-andr oidiOSkivy-ioskivy-iosAnacondaconda Using pipThe easiest way to install kivy is withpip, which installs kivy using either apre-compiled wheel, ifavailable, otherwise from source (see below). kivy providespre-compiled wheelsfor the supported Python versions on Windows, macOS, Linux, no wheels are availablepipwill build the package from sources ( on*BSD).Alternatively, installingfrom sourceis required for newer Python versions not listed above or if thewheels do not work or fail to run Setup terminal and pipBefore kivy can be installed, Python and pip needs to bepre-installed.

6 Then, start anew terminalthathasPython available. In the terminal, updatepipand other installation dependencies so you have thelatest version as follows (for linux users you may have to substitutepython3instead ofpythonandalso add a--userflag in the subsequent commands outside the virtual environment):python -m pip install --upgrade pip setuptools Create virtual environmentCreate a new virtual environment for your kivy project. A virtual environment will prevent possible in-stallation conflicts with other Python versions and packages. It s optionalbut strongly recommended:1. Create the virtual environment namedkivy_venvin your current directory:python -m virtualenv kivy_venv2. Activate the virtual environment. You will have to do this step from the current directoryeverytimeyou start a new terminal.

7 This sets up the environment so the newkivy_venvPython default CMD, in the command line do:kivy_venv\Scripts\activateIf you are in a bash terminal onWindows, instead do:source kivy_venv/Scripts/activateIf you are inlinuxormacOS, instead do:source kivy_venv/bin/activateYour terminal should now preface the path with something like(kivy_venv), indicating that thekivy_venvenvironment is active. If it doesn t say that, the virtual environment is not active and thefollowing won t Install KivyFinally, install kivy using one of the following options:Pre-compiled wheelsThe simplest is to install the current stable version ofkivyand optionallykivy_examplesfrom thekivy-team provided PyPi wheels. Simply do:python -m pip install " kivy [base]" kivy_examplesThis also installs the minimum dependencies of kivy .

8 To additionally install kivy withaudio/videosupport, install eitherkivy[base,media]orkivy[full]. See kivy s dependencies for the list the Raspberry Pi, you must additionally install the dependencies listed in source dependenciesbefore installing kivy sourceIf a wheel is not available or is not working, kivy can be installed from source with some additionalsteps. Installing from source means that kivy will be installed from source code and compiled directlyon your install the additional system dependencies listed for each platform: Windows, macOS, Linux,*BSD, RPiNote:In past, for macOS, Linux and BSD kivy required the installation of the SDL dependencies frompackage managers ( ). However, this is no longer officially supported as the versionof SDL provided by the package managers is often outdated and may not work with kivy as we try tokeep up with the latest SDL versions in order to support the latest features and can still install the SDL dependencies from package managers if you wish, but we no longeroffer support for , we recommend installing the SDL dependencies from source.

9 This is the same process ourCI uses to build the wheels. The SDL dependencies are built from source and installed into a all the build tools installed, you can now install the SDL dependencies from source for SDL sup-port (this is not needed on Windows as we provide pre-built SDL dependencies for Windows)In order to do so, we provide a script that will download and build the SDL dependencies from script is located in thetoolsdirectory of the kivy a directory to store the self-built dependencies and change into it:mkdir kivy -deps-build && cd kivy -deps-buildThen download the build tool script, according to your platform:OnmacOS:curl -O -o :curl -O -o the script executable:chmod +x , run the script:. script will download and build the SDL dependencies from source.

10 It will also install the depen-dencies into a directory namedkivy-dependencies. This directory will be used by kivy to build and installKivy from source with SDL will need to know where the SDL dependencies are installed. To do so, you must set theKIVY_DEPS_ROOT environment variable to the path of thekivy-dependenciesdirectory. For ex-ample, if you are in thekivy-deps-builddirectory, you can set the environment variable with:9export KIVY_DEPS_ROOT=$(pwd)/ kivy -dependenciesW ith the dependencies installed, andKIVY_DEPS_ROOTset you can now install kivy into the install the stable version of kivy , from the terminal do:python -m pip install " kivy [base]" kivy_examples --no-binary kivyTo install the latest cutting-edge kivy frommaster, instead do.