Kivy Documentation Release 2.1.0.Dev0
Total Page:16
File Type:pdf, Size:1020Kb
Kivy Documentation Release 2.1.0.dev0 The Kivy Developers September 20, 2021 CONTENTS I Kivy Project3 1 Philosophy 5 2 Contributing 7 3 FAQ 23 4 Contact Us 29 II Programming Guide 31 5 Kivy Basics 33 6 Controlling the environment 39 7 Configure Kivy 43 8 Architectural Overview 45 9 Events and Properties 49 10 Input management 59 11 Widgets 67 12 Graphics 87 13 Kv language 89 14 Integrating with other Frameworks 101 15 Packaging your application 105 16 Package licensing 123 III Tutorials 127 17 Pong Game Tutorial 129 18 A Simple Paint App 143 19 Crash Course 153 i IV API Reference 155 20 Kivy framework 157 21 Core Abstraction 265 22 Kivy module for binary dependencies. 299 23 Effects 301 24 Garden 307 25 Graphics 311 26 Input management 389 27 Kivy Language 413 28 External libraries 435 29 Modules 439 30 Network support 451 31 Storage 455 32 Tools 461 33 Widgets 463 V Appendix 713 34 License 715 Python Module Index 717 Index 719 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 KIVY PROJECT This part of the documentation explains the basic ideas behind Kivy’s design and why you’d want to use it. 3 4 CHAPTER ONE PHILOSOPHY In case you are wondering what Kivy is all about and what sets it apart from other solutions, this document is for you. 1.1 Why bother? Why would you want to use Kivy? After all, there are many great toolkits (or frameworks, or platforms) available out there – for free. You have Qt and Flash, to name just two good choices for application development. Many of these numerous solutions already support Multi-Touch, so what is it that makes Kivy special and worth using? 1.1.1 Fresh Kivy is made for today and tomorrow. Novel input methods such as Multi-Touch have become increas- ingly important. We created Kivy from scratch, specifically for this kind of interaction. That means we were able to rethink many things in terms of human computer interaction, whereas older (not to mean ‘outdated’, rather ‘well-established’) toolkits carry their legacy, which is often a burden. We’re not try- ing to force this new approach to using a computer into the corset of existing models (say single-pointer mouse interaction). We want to let it flourish and let you explore the possibilities. This is what really sets Kivy apart. 1.1.2 Fast Kivy is fast. This applies to both application development and application execution speeds. We have op- timized Kivy in many ways. We implement time-critical functionality on the C level to leverage the power of existing compilers. More importantly, we also use intelligent algorithms to minimize costly operations. We also use the GPU wherever it makes sense in our context. The computational power of today’s graphics cards surpasses that of today’s CPUs by far for some tasks and algorithms, espe- cially drawing. That’s why we try to let the GPU do as much of the work as possible, thus increasing performance considerably. 5 1.1.3 Flexible Kivy is flexible. This means it can be run on a variety of different devices, including Android powered smartphones and tablets. We support all major operating systems (Windows, Linux, OS X). Being flexible also means that Kivy’s fast-paced development allows it to adapt to new technologies quickly. More than once have we added support for new external devices and software protocols, sometimes even before they were released. Lastly, Kivy is also flexible in that it is possible to use it in combination with a great number of different third-party solutions. For example, on Windows we support WM_TOUCH, which means that any device that has Windows 7 Pen & Touch drivers will just work with Kivy. On OS X you can use Apple’s Multi-Touch capable devices, such as trackpads and mice. On Linux, you can use HID kernel input events. In addition to that, we support TUIO (Tangible User Interface Objects) and a number of other input sources. 1.1.4 Focused Kivy is focused. You can write a simple application with a few lines of code. Kivy programs are created using the Python programming language, which is incredibly versatile and powerful, yet easy to use. In addition, we created our own description language, the Kivy Language, for creating sophisticated user interfaces. This language allows you to set up, connect and arrange your application elements quickly. We feel that allowing you to focus on the essence of your application is more important than forcing you to fiddle with compiler settings. We took that burden off your shoulders. 1.1.5 Funded Kivy is actively developed by professionals in their field. Kivy is a community-influenced, profession- ally developed and commercially backed solution. Some of our core developers develop Kivy for a living. Kivy is here to stay. It’s not a small, vanishing student project. 1.1.6 Free Kivy is free to use. You don’t have to pay for it. You don’t even have to pay for it if you’re making money out of selling an application that uses Kivy. 6 CHAPTER TWO CONTRIBUTING There are many ways in which you can contribute to Kivy. Code patches are just one thing amongst others that you can submit to help the project. We also welcome feedback, bug reports, feature requests, documentation improvements, advertisement & advocating, testing, graphics contributions and many other ideas. Just talk to us if you want to help, and we will help you help us. 2.1 Discussions Discussions around Kivy development happens on Github’s issues and pull requests for specific things. For things that don’t fit in either, discussions happen on the #dev Discord channel, and on the kivy-dev google group. Please come ask for guidance if you are unsure about how to contribute, or you want confirmation about your ideas fitting in the project before working on them. If you want to ask for — or contribute — support, you can join the #support Discord channel, and the kivy-users google group. 2.2 Code of Conduct In the interest of fostering an open and welcoming community, we as contributors and maintainers need to ensure participation in our project and our sister projects is a harassment-free and postive experience for everyone. As such, it is vital that all interaction is conducted in a manner conveying respect, open-mindedness and gratitude. For a more comprehensive discussion of these guidelines, please refer to the Contributor Covenant. This document provides an accurate description of what is expected of you, both as a core developer or a first time contributor. 2.3 Feedback This is by far the easiest way to contribute something. If you’re using Kivy for your own project, don’t hesitate sharing. It doesn’t have to be a high-class enterprise app, obviously. It’s just incredibly motivating to know that people use the things you develop and what it enables them to do. If you have something that you would like to tell us, please don’t hesitate. Screenshots and videos are also very welcome! We’re also interested in the problems you had when getting started. Please feel encouraged to report any obstacles you encountered such as missing documentation, misleading directions or similar. We are perfectionists, so even if it’s just a typo, let us know. 7 2.4 Reporting an Issue If you found anything wrong, a crash, segfault, missing documentation, invalid spelling or just weird examples, please take 2 minutes to report the issue. 1. Move your logging level to debug by editing <user_directory>/.kivy/config.ini: [kivy] log_level= debug 2. Execute your code again, and copy/paste the complete output to http://gist.github.com/, in- cluding the log from Kivy and the python backtrace. 3. Open https://github.com/kivy/kivy/issues/ 4. Set the title of your issue 5. Explain exactly what to do to reproduce the issue and paste the link of the output posted on http://gist.github.com/ 6. Validate the issue and you’re done! If you are feeling up to it, you can also try to resolve the bug, and contribute by sending us the patch :) Read the next section to find out how to do this. 2.5 Code Contributions Code contributions (patches, new features) are the most obvious way to help with the project’s devel- opment. Since this is so common we ask you to follow our workflow to most efficiently work with us. Adhering to our workflow ensures that your contribution won’t be forgotten or lost. Also, your name will always be associated with the change you made, which basically means eternal fame in our code history (you can opt-out if you don’t want that). 2.5.1 Coding style • If you haven’t done it yet, read the PEP8 about coding style in python.