Quick search

Kivy Language

The Kivy language is a language dedicated to describing user interface and interactions. You could compare this language to Qt’s QML (http://qt.nokia.com), but we included new concepts such as rule definitions (which are somewhat akin to what you may know from CSS), templating and so on.

Changed in version 1.7.0: The Builder doesn’t execute canvas expressions in realtime anymore. It will pack all the expressions that need to be executed first and execute them after dispatching input, just before drawing the frame. If you want to force the execution of canvas drawing, just call Builder.sync.

An experimental profiling tool for the kv lang is also included. You can activate it by setting the environment variable KIVY_PROFILE_LANG=1. It will then generate an html file named builder_stats.html.

Overview

The language consists of several constructs that you can use:

Rules
A rule is similar to a CSS rule. A rule applies to specific widgets (or classes thereof) in your widget tree and modifies them in a certain way. You can use rules to specify interactive behaviour or use them to add graphical representations of the widgets they apply to. You can target a specific class of widgets (similar to the CSS concept of a class) by using the cls attribute (e.g. cls=MyTestWidget).
A Root Widget
You can use the language to create your entire user interface. A kv file must contain only one root widget at most.
Dynamic Classes
(introduced in version 1.7.0) Dynamic classes let you create new widgets and rules on-the-fly, without any Python declaration.
Templates (deprecated)
(introduced in version 1.0.5, deprecated from version 1.7.0) Templates were used to populate parts of an application, such as styling the content of a list (e.g. icon on the left, text on the right). They are now deprecated by dynamic classes.

Syntax of a kv File

A Kivy language file must have .kv as filename extension.

The content of the file should always start with the Kivy header, where version must be replaced with the Kivy language version you’re using. For now, use 1.0:

#:kivy `1.0`

# content here

The content can contain rule definitions, a root widget, dynamic class definitions and templates:

# Syntax of a rule definition. Note that several Rules can share the same
# definition (as in CSS). Note the braces: they are part of the definition.
<Rule1,Rule2>:
    # .. definitions ..

<Rule3>:
    # .. definitions ..

# Syntax for creating a root widget
RootClassName:
    # .. definitions ..

# Syntax for creating a dynamic class
<NewWidget@BaseClass>:
    # .. definitions ..

# Syntax for create a template
[TemplateName@BaseClass1,BaseClass2]:
    # .. definitions ..

Regardless of whether it’s a rule, root widget, dynamic class or template you’re defining, the definition should look like this:

# With the braces it's a rule. Without them, it's a root widget.
<ClassName>:
    prop1: value1
    prop2: value2

    canvas:
        CanvasInstruction1:
            canvasprop1: value1
        CanvasInstruction2:
            canvasprop2: value2

    AnotherClass:
        prop3: value1

Here prop1 and prop2 are the properties of ClassName and prop3 is the property of AnotherClass. If the widget doesn’t have a property with the given name, an ObjectProperty will be automatically created and added to the instance.

AnotherClass will be created and added as a child of the ClassName instance.

  • The indentation is important and must be consistent. The spacing must be a multiple of the number of spaces used on the first indented line. Spaces are encouraged: mixing tabs and spaces is not recommended.
  • The value of a property must be given on a single line (for now at least).
  • The canvas property is special: you can put graphics instructions in it to create a graphical representation of the current class.

Here is a simple example of a kv file that contains a root widget:

#:kivy 1.0

Button:
    text: 'Hello world'

Changed in version 1.7.0: The indentation is not limited to 4 spaces anymore. The spacing must be a multiple of the number of spaces used on the first indented line.

Both the load_file() and the load_string() methods return the root widget defined in your kv file/string. They will also add any class and template definitions to the Factory for later usage.

Value Expressions, on_property Expressions, and Reserved Keywords

When you specify a property’s value, the value is evaluated as a Python expression. This expression can be static or dynamic, which means that the value can use the values of other properties using reserved keywords.

self

The keyword self references the “current widget instance”:

Button:
    text: 'My state is %s' % self.state
root

This keyword is available only in rule definitions and represents the root widget of the rule (the first instance of the rule):

<Widget>:
    custom: 'Hello world'
    Button:
        text: root.custom
app

This keyword always refers to your app instance. It’s equivalent to a call to kivy.app.App.get_running_app() in Python.:

Label:
    text: app.name
args

This keyword is available in on_<action> callbacks. It refers to the arguments passed to the callback.:

TextInput:
    on_focus: self.insert_text("Focus" if args[1] else "No focus")

Furthermore, if a class definition contains an id, you can use it as a keyword:

<Widget>:
    Button:
        id: btn1
    Button:
        text: 'The state of the other button is %s' % btn1.state

Please note that the id will not be available in the widget instance: it is used exclusively for external references. id is a weakref to the widget, and not the widget itself. The widget itself can be accessed with id.__self__ (btn1.__self__ in this case).

Valid expressons

There are two places that accept python statments in a kv file: after a property, which assigns to the property the result of the expression (such as the text of a button as shown above) and after a on_property, which executes the statement when the property is updated (such as on_state).

In the former case, the expression can only span a single line, cannot be extended to multiple lines using newline escaping, and must return a value. An example of a valid expression is text: self.state and ('up' if self.state == 'normal' else 'down').

In the latter case, multiple single line statements are valid including multi-line statements that escape their newline, as long as they don’t add an indentation level.

Examples of valid statements are:

on_press: if self.state == 'normal': print('normal')
on_state:
    if self.state == 'normal': print('normal')
    else: print('down')
    if self.state == 'normal':         print('multiline normal')
    for i in range(10): print(i)
    print([1,2,3,4,
    5,6,7])

An example of a invalid statement:

on_state:
    if self.state == 'normal':
        print('normal')

Relation Between Values and Properties

When you use the Kivy language, you might notice that we do some work behind the scenes to automatically make things work properly. You should know that Properties implement the Observer Design Pattern. That means that you can bind your own function to be called when the value of a property changes (i.e. you passively observe the property for potential changes).

The Kivy language detects properties in your value expression and will create create callbacks to automatically update the property via your expression when changes occur.

Here’s a simple example that demonstrates this behaviour:

Button:
    text: str(self.state)

In this example, the parser detects that self.state is a dynamic value (a property). The state property of the button can change at any moment (when the user touches it). We now want this button to display its own state as text, even as the state changes. To do this, we use the state property of the Button and use it in the value expression for the button’s text property, which controls what text is displayed on the button (We also convert the state to a string representation). Now, whenever the button state changes, the text property will be updated automatically.

Remember: The value is a python expression! That means that you can do something more interesting like:

Button:
    text: 'Plop world' if self.state == 'normal' else 'Release me!'

The Button text changes with the state of the button. By default, the button text will be ‘Plop world’, but when the button is being pressed, the text will change to ‘Release me!’.

Graphical Instructions

The graphical instructions are a special part of the Kivy language. They are handled by the ‘canvas’ property definition:

Widget:
    canvas:
        Color:
            rgb: (1, 1, 1)
        Rectangle:
            size: self.size
            pos: self.pos

All the classes added inside the canvas property must be derived from the Instruction class. You cannot put any Widget class inside the canvas property (as that would not make sense because a widget is not a graphics instruction).

If you want to do theming, you’ll have the same question as in CSS: which rules have been executed first? In our case, the rules are executed in processing order (i.e. top-down).

If you want to change how Buttons are rendered, you can create your own kv file and add something like this:

<Button>:
    canvas:
        Color:
            rgb: (1, 0, 0)
        Rectangle:
            pos: self.pos
            size: self.size
        Rectangle:
            pos: self.pos
            size: self.texture_size
            texture: self.texture

This will result in buttons having a red background with the label in the bottom left, in addition to all the preceding rules. You can clear all the previous instructions by using the Clear command:

<Button>:
    canvas:
        Clear
        Color:
            rgb: (1, 0, 0)
        Rectangle:
            pos: self.pos
            size: self.size
        Rectangle:
            pos: self.pos
            size: self.texture_size
            texture: self.texture

Then, only your rules that follow the Clear command will be taken into consideration.

Dynamic classes

Dynamic classes allow you to create new widgets on-the-fly, without any python declaration in the first place. The syntax of the dynamic classes is similar to the Rules, but you need to specify the base classes you want to subclass.

The syntax looks like:

# Simple inheritance
<NewWidget@Button>:
    # kv code here ...

# Multiple inheritance
<NewWidget@ButtonBehavior+Label>:
    # kv code here ...

The @ character is used to seperate your class name from the classes you want to subclass. The Python equivalent would have been:

# Simple inheritance
class NewWidget(Button):
    pass

# Multiple inheritance
class NewWidget(ButtonBehavior, Label):
    pass

Any new properties, usually added in python code, should be declared first. If the property doesn’t exist in the dynamic class, it will be automatically created as an ObjectProperty (pre 1.8.0) or as an appropriate typed property (from version 1.8.0).

Changed in version 1.8.0: If the property value is an expression that can be evaluated right away (no external binding), then the value will be used as default value of the property, and the type of the value will be used for the specialization of the Property class. In other terms: if you declare hello: “world”, a new StringProperty will be instanciated, with the default value “world”. Lists, tuples, dictionaries and strings are supported.

Let’s illustrate the usage of theses dynamic classes with an implementation of a basic Image button. We could derive our classes from the Button and just add a property for the image filename:

<ImageButton@Button>:
    source: None

    Image:
        source: root.source
        pos: root.pos
        size: root.size

# let's use the new classes in another rule:
<MainUI>:
    BoxLayout:
        ImageButton:
            source: 'hello.png'
            on_press: root.do_something()
        ImageButton:
            source: 'world.png'
            on_press: root.do_something_else()

In Python, you can create an instance of the dynamic class as follows:

from kivy.factory import Factory
button_inst = Factory.ImageButton()

Note

Using dynamic classes, a child class can be declared before it’s parent. This however, leads to the unintuitive situation where the parent properties/methods override those of the child. Be careful if you choose to do this.

Templates

Changed in version 1.7.0: Template usage is now deprecated. Please use Dynamic classes instead.

Syntax of templates

Using a template in Kivy requires 2 things :

  1. a context to pass for the context (will be ctx inside template).
  2. a kv definition of the template.

Syntax of a template:

# With only one base class
[ClassName@BaseClass]:
    # .. definitions ..

# With more than one base class
[ClassName@BaseClass1,BaseClass2]:
    # .. definitions ..

For example, for a list, you’ll need to create a entry with a image on the left, and a label on the right. You can create a template for making that definition easier to use. So, we’ll create a template that uses 2 entries in the context: an image filename and a title:

[IconItem@BoxLayout]:
    Image:
        source: ctx.image
    Label:
        text: ctx.title

Then in Python, you can instanciate the template using:

from kivy.lang import Builder

# create a template with hello world + an image
# the context values should be passed as kwargs to the Builder.template
# function
icon1 = Builder.template('IconItem', title='Hello world',
    image='myimage.png')

# create a second template with other information
ctx = {'title': 'Another hello world',
       'image': 'myimage2.png'}
icon2 = Builder.template('IconItem', **ctx)
# and use icon1 and icon2 as other widget.

Template example

Most of time, when you are creating a screen in the kv lang, you use a lot of redefinitions. In our example, we’ll create a Toolbar, based on a BoxLayout, and put in a few Image widgets that will react to the on_touch_down event.:

<MyToolbar>:
    BoxLayout:
        Image:
            source: 'data/text.png'
            size: self.texture_size
            size_hint: None, None
            on_touch_down: self.collide_point(*args[1].pos) and root.create_text()

        Image:
            source: 'data/image.png'
            size: self.texture_size
            size_hint: None, None
            on_touch_down: self.collide_point(*args[1].pos) and root.create_image()

        Image:
            source: 'data/video.png'
            size: self.texture_size
            size_hint: None, None
            on_touch_down: self.collide_point(*args[1].pos) and root.create_video()

We can see that the size and size_hint attribute are exactly the same. More than that, the callback in on_touch_down and the image are changing. Theses can be the variable part of the template that we can put into a context. Let’s try to create a template for the Image:

[ToolbarButton@Image]:

    # This is the same as before
    size: self.texture_size
    size_hint: None, None

    # Now, we are using the ctx for the variable part of the template
    source: 'data/%s.png' % ctx.image
    on_touch_down: self.collide_point(*args[1].pos) and ctx.callback()

The template can be used directly in the MyToolbar rule:

<MyToolbar>:
    BoxLayout:
        ToolbarButton:
            image: 'text'
            callback: root.create_text
        ToolbarButton:
            image: 'image'
            callback: root.create_image
        ToolbarButton:
            image: 'video'
            callback: root.create_video

That’s all :)

Template limitations

When you are creating a context:

  1. you cannot use references other than “root”:
<MyRule>:
    Widget:
        id: mywidget
        value: 'bleh'
    Template:
        ctxkey: mywidget.value # << fail, this reference mywidget id
  1. not all of the dynamic parts will be understood:
<MyRule>:
    Template:
        ctxkey: 'value 1' if root.prop1 else 'value2' # << even if
        # root.prop1 is a property, the context will not update the
        # context

Redefining a widget’s style

Sometimes we would like to inherit from a widget in order to use its Python properties without also using its .kv defined style. For example, we would like to inherit from a Label, but we would also like to define our own canvas instructions instead of automatically using the canvas instructions inherited from the Label. We can achieve this by prepending a dash (-) before the class name in the .kv style definition.

In myapp.py:

class MyWidget(Label):
    pass

and in my.kv:

<-MyWidget>:
    canvas:
        Color:
            rgb: 1, 1, 1
        Rectangle:
            size: (32, 32)

MyWidget will now have a Color and Rectangle instruction in its canvas without any of the instructions inherited from the Label.

Lang Directives

You can use directives to add declarative commands, such as imports or constant definitions, to the lang files. Directives are added as comments in the following format:

#:<directivename> <options>

import <package>

New in version 1.0.5.

Syntax:

#:import <alias> <package>

You can import a package by writing:

#:import os os

<Rule>:
    Button:
        text: os.getcwd()

Or more complex:

#:import ut kivy.utils

<Rule>:
    canvas:
        Color:
            rgba: ut.get_random_color()

New in version 1.0.7.

You can directly import classes from a module:

#: import Animation kivy.animation.Animation
<Rule>:
    on_prop: Animation(x=.5).start(self)

set <key> <expr>

New in version 1.0.6.

Syntax:

#:set <key> <expr>

Set a key that will be available anywhere in the kv. For example:

#:set my_color (.4, .3, .4)
#:set my_color_hl (.5, .4, .5)

<Rule>:
    state: 'normal'
    canvas:
        Color:
            rgb: my_color if self.state == 'normal' else my_color_hl

include <file>

New in version 1.8.1.

Syntax:

#:include [force] <file>

Includes an external kivy file. This allows you to split complex widgets into their own files. If the include is forced, the file will first be unloaded and then reloaded again. For example:

# Test.kv
#:include mycomponent.kv
#:include force mybutton.kv

<Rule>:
    state: 'normal'
    MyButton:
    MyComponent:
# mycomponent.kv
#:include mybutton.kv

<MyComponent>:
    MyButton:
# mybutton.kv

<MyButton>:
    canvas:
        Color:
            rgb: (1.0, 0.0, 0.0)
        Rectangle:
            pos: self.pos
            size: (self.size[0]/4, self.size[1]/4)
kivy.lang.Builder = <kivy.lang.BuilderBase object at 0x947a5cc>

Main instance of a BuilderBase.

class kivy.lang.BuilderBase[source]

Bases: object

The Builder is responsible for creating a Parser for parsing a kv file, merging the results into its internal rules, templates, etc.

By default, Builder is a global Kivy instance used in widgets that you can use to load other kv files in addition to the default ones.

apply(widget)[source]

Search all the rules that match the widget and apply them.

load_file(filename, **kwargs)[source]

Insert a file into the language builder and return the root widget (if defined) of the kv file.

Parameters :
rulesonly: bool, defaults to False

If True, the Builder will raise an exception if you have a root widget inside the definition.

load_string(string, **kwargs)[source]

Insert a string into the Language Builder and return the root widget (if defined) of the kv string.

Parameters :
rulesonly: bool, defaults to False

If True, the Builder will raise an exception if you have a root widget inside the definition.

match(widget)[source]

Return a list of ParserRule objects matching the widget.

sync()[source]

Execute all the waiting operations, such as the execution of all the expressions related to the canvas.

New in version 1.7.0.

template(*args, **ctx)[source]

Create a specialized template using a specific context. .. versionadded:: 1.0.5

With templates, you can construct custom widgets from a kv lang definition by giving them a context. Check Template usage.

unbind_widget(uid)[source]

(internal) Unbind all the handlers created by the rules of the widget. The kivy.uix.widget.Widget.uid is passed here instead of the widget itself, because we are using it in the widget destructor.

New in version 1.7.2.

unload_file(filename)[source]

Unload all rules associated with a previously imported file.

New in version 1.0.8.

Warning

This will not remove rules or templates already applied/used on current widgets. It will only effect the next widgets creation or template invocation.

class kivy.lang.BuilderException(context, line, message)[source]

Bases: kivy.lang.ParserException

Exception raised when the Builder failed to apply a rule on a widget.

class kivy.lang.Parser(**kwargs)[source]

Bases: object

Create a Parser object to parse a Kivy language file or Kivy content.

parse(content)[source]

Parse the contents of a Parser file and return a list of root objects.

parse_level(level, lines, spaces=0)[source]

Parse the current level (level * spaces) indentation.

strip_comments(lines)[source]

Remove all comments from all lines in-place. Comments need to be on a single line and not at the end of a line. i.e. a comment line’s first non-whitespace character must be a #.

class kivy.lang.ParserException(context, line, message)[source]

Bases: exceptions.Exception

Exception raised when something wrong happened in a kv file.