Getting Started

Introduction

Start Developing Kivy Apps right away!

Creating Kivy apps is fun and rewarding. This guide should be the perfect starting point to get you on the right track for app development. You will require a basic knowledge of Python to follow this introduction.

../_images/gs-introduction.png

If you need more background about Python language, you might be interested in these tutorials:

Using Kivy on your computer, you can create apps that run on:

  • Desktop computers: MacOSX, Linux, Windows.
  • iOs Devices: iPad, iPhone
  • Android devices: Tablets, phones.
  • Any other touch-enabled professional/homebrew devices supporting TUIO (Tangible User Interface Objects).

Kivy empowers you with the freedom of writing your code once and having it run as-is on different platforms.

Follow this guide to get the tools you need, understand the major concepts and learn best practices. As this is an introduction, pointers to more information will be provided at the end of each section.

As you proceed through the guide, you will, using Kivy:

  • Learn: The basics of programming with the Kivy language.
  • Explore: The Kivy framework.
  • Create: simple cross-platform app.
  • Package: for your choice of platform.

Finally, you will learn how to Deploy on a device of your choice.

Each section of the guide introduces a new topic, trying to give you enough information to get started and links to related articles for more in-depth explanations. When you are done with this guide, you’ll be able to develop Kivy apps and you will know where to look for information for the more challenging stuff your innovative applications will require.

Enough introductions, let’s get down to business.

Installation

Installing Kivy

With Kivy, you can use your favourite development environment to start coding your App. To get started, you need to download the latest version of Kivy:

After download, please refer to the installation instructions for your specific platform:

Windows MacOSX Linux

Development Version

If you want the development version of Kivy, so you can use the latest additions to the framework, you can get the source code from github:

git clone http://github.com/kivy/kivy

Take a look at our instructions on installation of the Development Version

A first App

Jump into the code

Immerse yourself in the world of Kivy with your first App.

../_images/gs-tutorial.png

The Pong Game Tutorial introduces the fundamental design patterns and the application development process. As you follow the tutorial, you will create a simple app. You will also learn how to run the app on your OS. The simple steps in the tutorial introduce elegant, useful concepts that you will use over and over again in app development.

The Pong Game Tutorial is the most important article in the road map. It lays the foundation for the concepts that you will learn more about later. Each of the other articles expands on one of those concepts.

Properties

Using Kivy’s Properties

Kivy introduce a new way of declaring the properties within a class. Before:

class MyClass(object):
    def __init__(self):
        super(MyClass, self).__init__()
        self.numeric_var = 1

After, using Kivy’s properties:

class MyClass(EventDispatcher):
    numeric_var = NumericProperty(1)

Theses properties implement the Observer pattern. You can:

  • Allow manipulating your widgets in kv language more easily
  • Automatically observe any changes and dispatch functions/code accordingly
  • Check and validate values
  • Optimize memory management

To use them, you have to declare them at class level. That is, directly in the class, not in any method of the class. A property is a class attribute that will automatically create instance attributes. Each property by default provides an on_<propertyname> event that is called whenever the property’s state/value changes .

Kivy provides the following properties:
NumericProperty, StringProperty, ListProperty, ObjectProperty, BooleanProperty, BoundedNumericProperty, OptionProperty, ReferenceListProperty, AliasProperty, DictProperty,

For an in-depth explaination, look at Properties

Kv Design Language

Designing with the kv language.

Kivy provides a design language specifically geared towards ease of GUI Design, which makes it easier to separate interface design and logic from internal design and logic. For example:

../_images/gs-lang.png

In the above code :

<LoginScreen>:  # every class in your app can be represented by a rule like this in the kv file
    GridLayout: # this is how you add your widget/layout to the parent (note the indentation).
        rows: 2 # this how you set each property of your widget/layout

That’s it, that’s how simple it is to design your GUI in the kv language. To get a more in-depth understanding look at Introduction to the Kivy Language

Events

Events

Kivy is mostly event-based, that’s mean the flow of the program is determined by events.

Clock events

../_images/gs-events-clock.png

The Clock object allows you to schedule a function call in the future, as a one-time event with schedule_once(), or as a repetitive event with schedule_interval().

You can also create Triggered events with create_trigger(), multiple call to a trigger will schedule a function call only once.

Input events

../_images/gs-events-input.png

All the mouses click, touchs, scroll wheel are part of the MotionEvent, extended by Input Postprocessing, dispatched through the on_motion in Window, then in the on_touch_down(), on_touch_move(), on_touch_up() in Widget

For an in-depth explaination, have a look at Input management.

Class events

../_images/gs-events-class.png

Our base class EventDispatcher, used by Widget, use the power of ours Properties for dispatching changes. IE, when a widget changes its position or size, an event is fired.

In addition, you have the possibility to create your own event using register_event_type(), as the on_press/on_release in Button.

Another thing to note is that if you override an event, you become responsible for implementing all its behaviour previously handled by the base class. The easiest way to do this is to call super():

def on_touch_down(self, touch):
    if super(OurClassName, self).on_touch_down(touch):
        return True
    if not self.collide_point(touch.x, touch.y):
        return False
    print 'you touched me!'
    return True

Get more familiar with events by reading the Events documentation.

Non-widget stuff

Kivy FrameWork
Animation is used to change a Widget’s properties (size/pos/center...), to a target value, in a target time. Various transition functions are provided. Using them, you can animate widgets and build very smooth UI behaviours. animation_img
Atlas is a class for managing texture maps, i.e. packing multiple textures into one image. Using it allows you to reduce the number of images to load and speed up the application start. atlas_img
Clock provides you with a convenient way to do jobs at set time intervals and is preferred over sleep() which would block the kivy Event Loop. These intervals can be set relative to the OpenGL Drawing instructions, before or after frame. Clock also provides you with a way to create triggered events that are grouped together and only called once before the next frame.
UrlRequest is useful to do asynchronous requests without blocking the event loop, and manage the result and progress with callbacks.  

Layouts

Arranging Your Widgets

Layouts are used to arrange widgets in a perticular manner:

AnchorLayout:   widgets can be anchored to 'top', 'bottom', 'left', 'right', 'center'
BoxLayout:      widgets are arranged in a box in either 'vertical' or 'horizontal' orientation
FloatLayout:    Widgets are essentially unrestricted
RelativeLayout: Child widgets are positioned relative to the layout.
GridLayout:     widgets are arranged in a grid defined by `rows` and `cols` properties
StackLayout:    widgets are stacked in `lr-tb` (left to right then top to bottom) or `tb-lr` order

Size_hint: defines the size of a widget in parent space as a percentage. Values are restricted to the range 0.0 - 1.0 i.e. 0.01 = 1% and 1. = 100%. pos_hint: is used to place the widget relative to the parent.

size_hint and pos_hint are used to calculate widget’s size and position only if the value/s are not set to None. However one can set these to None and provide direct values in screen coordinates.

For a detailed look at how you can arrange widgets using layouts look in AnchorLayout BoxLayout FloatLayout GridLayout StackLayout RelativeLayout

Drawing

Graphics Instructions, Canvas

Each widget has a canvas, i.e. a place to draw on. The canvas is a group of instructions that should be executed whenever there is a change to the widget’s graphics representation. You can add two types of instructions to the canvas, context instructions and vertex instructions. You can add instructions either from Python or from kv (the preferred way). If you add them from kv, the advantage is that they are automatically updated when any property they depend on changes. In Python, you need to do this yourself.

../_images/gs-drawing.png

In both cases the canvas of the MyWidget is re-drawn whenever the position or the size of the widget changes.

You can use canvas.before or canvas.after . This allows you to separate your instructions based on when you want them to happen.

For an in-depth look at how Kivy’s graphics are handled, look here.

Examples

Follow through the examples.
Directory Filename/s Example Description
  • ./examples/animation
  • animate.py
  • ./examples/application
  • app_with_build.py
  • app_with_kv.py
  • app_with_kv_in_template1.py
  • Application example using build()
  • Application from a .kv
  • Application from a kv_directory
  • ./examples/canvas
  • bezier.py
  • canvas_stress.py
  • mesh.py
  • multitexture.py
  • stencil_canvas.py
  • How to draw Bezier Lines
  • Stress test Canvas
  • How to use Mesh in kivy
  • How to handle multiple textures with shader
  • How to use Stencil on widget canvas
  • ./examples/demo:
  • camera_puzzle.py
  • A puzzle using Camera output
  • ./examples/demo/pictures
  • main.py
  • ./examples/demo/shadereditor
  • main.py
  • How to use fragment and vertex shaders
  • ../examples/demo/showcase
  • main.py
  • Showcase of widgets and layouts used in kivy.
  • ./examples/demo/touchtracer
  • main.py
  • Draw lines under every detected touch.
  • A good place to understand how touch events work in kivy.
  • ./examples/frameworks/twisted
  • echo_client_app.py
  • echo_server_app.py
  • ./examples/gestures
  • gesture_board.py
  • A clean board to try out gestures.
  • ./examples/guide/designwithkv
  • main.py
  • ./examples/guide/firstwidget
  • 1_skeleton.py
  • 2_print_touch.py
  • 3_draw_ellipse.py
  • 4_draw_line.py
  • 5_random_colors.py
  • 6_button.py
  • ./examples/guide/quickstart
  • main.py
  • ./examples/kinect
  • main.py
  • Howto use kinect for input.
  • ./examples/kv
  • kvrun.py
  • load kv files, use kv lang to load different widgets.
  • ./examples/RST_Editor
  • main.py
  • ./examples/shader
  • plasma.py
  • shadertree.py
  • How to use different Shaders.
  • ./examples/widgets
  • accordion_1.py
  • asyncimage.py
  • boxlayout_pos_hint.py
  • bubble_test.py
  • customcollide.py
  • fbowidget.py
  • image_mipmap.py
  • keyboardlistener.py
  • label_mipmap.py
  • label_with_markup.py
  • popup_with_kv.py
  • rstexample.py
  • scatter.py
  • screenmanager.py
  • scrollview.py
  • spinner.py
  • tabbedpanel.py
  • tabbed_panel_showcase.py
  • textalign.py
  • textinput.py
  • unicode_textinput.py
  • videoplayer.py
  • Usage and Showcase of Accordion Widget.
  • Usage and Showcase of AsyncImage Widget.
  • Showcase of pos_hint under BoxLayout BoxLayout
  • Usage and Showcase of Bubble Widget.
  • Test for collision with custom shaped widget
  • Usage of FBO to speed up graphics.
  • How to use Image widget with mipmap.
  • listen to the keyboard input and spew result to console.
  • How to use Label widget with
  • Useage of Label widget with markup.
  • Useage of Popup widget with kv language
  • Usage and Showcase of RstDocument Widget.
  • Usage and Showcase of Scatter Widget.
  • Usage and showase of ScreenManager Module.
  • Usage and Showcase of ScrollView Widget.
  • Usage and Showcase of Spinner Widget.
  • Usage of a simple TabbedPanel
  • Advanced Showcase of TabbedPanel
  • Usage of text alignment in Label widget.
  • Usage and Showcase of TextInput Widget.
  • Showcase of unicode text in TextInput Widget.
  • Usage and options of VideoPlayer Widget.
  • ./examples/widgets/sequenced_images:
  • main.py
  • Showcase usage of sequenced images: gif, images in .zip.

Diving in

Endless Possibilities

To further get into kivy take a look at Welcome to Kivy

Kivy comes with a set of Examples in the kivy_installation/examples directory. You should try modifying/improving/adapting them to your needs.

Browse the snippet wiki . You can even add your snippet in the user snippets section.

Understand the basics about kivy graphics

Take a look at the built-in widgets

Follow the Programming Guide to get even more familiar with kivy.

See how to use different Modules like the Inspector for live inspection in the modules section.

Learn how to handle custom Input

See how kivy has been extended with extensions support.

Familiarize yourself with the kivy framework

Kivy is open source so you can contribute , take a look at Contributing section to see the guidelines.