Kivy Documentation Release 1.5.2-dev www.kivy.org CONTENTS I User’s Guide3 1 Philosophy 5 1.1 Why bother?............................................5 2 Installation 7 2.1 Stable Version............................................7 2.2 Development Version....................................... 18 3 Programming Guide 21 3.1 Quickstart.............................................. 21 3.2 How to read the documentation................................. 22 3.3 Controling the environment.................................... 23 3.4 Configure Kivy........................................... 24 3.5 Architectural Overview...................................... 25 3.6 Your First Widget.......................................... 28 3.7 Widget tree............................................. 36 3.8 Events................................................ 37 3.9 Input management......................................... 40 3.10 Introduction to the Kivy Language................................ 43 3.11 Designing with the Kivy Language............................... 47 3.12 Integrating with other Frameworks............................... 48 3.13 Packaging your application.................................... 51 4 Tutorials 61 4.1 Pong Game Tutorial........................................ 61 5 Contributing 73 5.1 Feedback.............................................. 73 5.2 Reporting an Issue......................................... 73 5.3 Code Contributions........................................ 74 5.4 Documentation Contributions.................................. 76 5.5 Unit tests contributions...................................... 77 6 FAQ 81 6.1 Technical FAQ........................................... 81 6.2 Android FAQ............................................ 82 6.3 Project FAQ............................................. 82 7 Contact Us 85 7.1 Issue Tracker............................................ 85 7.2 Mail................................................. 85 7.3 IRC.................................................. 85 i 8 Programming Guide 2 87 8.1 Kivy Basics............................................. 87 8.2 Events and Properties....................................... 101 8.3 Widgets............................................... 106 8.4 Graphics............................................... 107 8.5 Kv language............................................. 109 8.6 Best Practices............................................ 114 8.7 Advanced Graphics........................................ 114 8.8 Packaging.............................................. 114 II API Reference 115 9 Kivy framework 117 9.1 Animation.............................................. 118 9.2 Application............................................. 128 9.3 Asynchronous data loader.................................... 135 9.4 Atlas................................................. 136 9.5 Cache manager........................................... 138 9.6 Clock object............................................. 140 9.7 Configuration object........................................ 143 9.8 Event dispatcher.......................................... 146 9.9 Event loop management...................................... 147 9.10 Factory object............................................ 149 9.11 Gesture recognition........................................ 150 9.12 Interactive launcher........................................ 151 9.13 Kivy Language........................................... 154 9.14 Logger object............................................ 161 9.15 Metrics................................................ 162 9.16 Parser utilities............................................ 164 9.17 Properties.............................................. 165 9.18 Resources management...................................... 171 9.19 Support............................................... 171 9.20 Utils................................................. 172 9.21 Vector................................................ 173 9.22 Weak Method............................................ 176 10 Adapters 179 10.1 Adapter............................................... 179 10.2 DictAdapter............................................. 180 10.3 List Item View Argument Converters.............................. 181 10.4 ListAdapter............................................. 181 10.5 SelectableDataItem......................................... 184 10.6 SimpleListAdapter......................................... 184 11 Core Abstraction 187 11.1 Audio................................................ 187 11.2 Camera............................................... 188 11.3 Clipboard.............................................. 189 11.4 OpenGL............................................... 189 11.5 Image................................................ 190 11.6 Spelling............................................... 192 11.7 Text.................................................. 193 11.8 Video................................................. 195 11.9 Window............................................... 196 ii 12 Extension Support 203 13 Graphics 205 13.1 The basics.............................................. 205 13.2 GL Reloading mechanism..................................... 205 13.3 Canvas................................................ 221 13.4 Context instructions........................................ 224 13.5 Context management....................................... 227 13.6 Framebuffer............................................. 228 13.7 GL instructions........................................... 230 13.8 Graphics compiler......................................... 231 13.9 OpenGL............................................... 231 13.10 OpenGL utilities.......................................... 240 13.11 Shader................................................ 241 13.12 Stencil instructions......................................... 243 13.13 Texture................................................ 244 13.14 Transformation........................................... 249 13.15 Vertex Instructions......................................... 250 14 Input management 257 14.1 Input Postprocessing........................................ 259 14.2 Providers.............................................. 260 14.3 Input recorder........................................... 265 14.4 Motion Event............................................ 267 14.5 Motion Event Factory....................................... 271 14.6 Motion Event Provider...................................... 271 14.7 Motion Event Shape........................................ 271 15 External libraries 273 15.1 jinja2.debug............................................. 273 16 Modules 275 16.1 Activate module in config..................................... 275 16.2 Activate module in Python.................................... 275 16.3 Create my own module...................................... 275 16.4 Inspector............................................... 276 16.5 Keybinding............................................. 276 16.6 Monitor module.......................................... 276 16.7 Recorder module.......................................... 276 16.8 Screen................................................ 277 16.9 Touchring.............................................. 277 17 Network support 279 17.1 Url Request............................................. 279 18 Widgets 283 18.1 Abstract View............................................ 283 18.2 Accordion.............................................. 284 18.3 Anchor Layout........................................... 288 18.4 Box Layout............................................. 289 18.5 Bubble................................................ 290 18.6 Button................................................ 293 18.7 Camera............................................... 294 18.8 Carousel............................................... 295 18.9 CheckBox.............................................. 297 18.10 Code Input............................................. 298 18.11 Drop-Down List.......................................... 298 iii 18.12 FileChooser............................................. 300 18.13 Float Layout............................................. 305 18.14 Grid Layout............................................. 306 18.15 Image................................................ 309 18.16 Label................................................. 311 18.17 Layout................................................ 316 18.18 List View.............................................. 317 18.19 ModalView............................................. 327 18.20 Popup................................................ 329 18.21 Progress Bar............................................. 331 18.22 Relative Layout........................................... 331 18.23 Scatter................................................ 332 18.24 Screen Manager........................................... 335 18.25 Scroll View............................................. 340 18.26 Settings............................................... 343 18.27 Slider................................................. 349 18.28 Spinner............................................... 351 18.29 Splitter................................................ 352 18.30 Stack Layout............................................ 354 18.31 Stencil View............................................. 355 18.32 Switch................................................ 355 18.33