Kivy language — Kivy v1.0.1-dev documentation

# Kivy language

Kivy language is a language dedicated for describing user interface and interactions. You could compare this language to QML of Qt (http://qt.nokia.com), but we are including new concept like the rules definitions, templating and so on.

## Overview

The language permit you to create:

> Rule
>   The rule is like CSS rules. You create a rule to match a specific class or widget in your tree. You can automatically create interactions or adding graphicals instructions to a specific widget (like all the widgets with the attribute cls=test).
> Root widget
>   You can use the language to create your user interface. A kv file can contain only one root widget.
> Template

>   This will be used to create part of your application, like the list content. If you want to design the look of an entry in a list (icon in the left, text in the right), you will use Template for that.

>   For the moment, templating are not yet designed in the language, we are still working on it. Check the issue #17 (https://github.com/tito/kivy/issues#issue/17)

## Syntax of a kv file

A kivy language file must be ended by the .kv extension.

The content of the file must 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 `version`

    `content`

The content can contain rules, root widget and template:

    # syntax of a rule
    <Rule1,Rule2>:
        .. definitions ..

    <Rule3>:
        .. definitions ..

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

Whatever is it’s an rule, root widget or template, the definition should look like this:

    <ClassName>:
        prop1: value1
        prop2: value2

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

        AnotherClass:
            prop3: value1

prop1 and prop2 are the properties of ClassName and prop3 is the property of AnotherClass. If the property doesn’t exist in the class, an `ObjectProperty` will be automatically created and added to the instance.

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

- The indentation is important, and must be 4 spaces. Tabs are not allowed.
- The value of a property must be single line. (we may change this in a future

version.) - The canvas property is special: you can put graphics class inside it to create your graphical representation of the current class.

Here is an example of a kv file that contain a root widget:

    #:kivy 1.0

    Button:
        text: 'Hello world'

## Value expression and reserved keyword

The value is a python expression. This expression can be static or dynamic, that’s mean the value can use the values of other properties using reserved keywords.

> self

>   The keyword self reference the “current widget instance”:

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

> root

>   This keyword is available only in rules definition, and represent the root widget of the rule (the first instance of the rule):

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

Also, if a class definition contain an id, you can use it as a keyword:

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

Please note that the id will be not available in the Widget instance: the id attribute will be not used.

## Relation between values and properties

When you use kv language, we are doing magical stuff to automatically get things work. You must know that Properties implement the observer pattern: you can bind your own function to be called when the value of a property change.

Kv language detect properties in your value, and create callback to automatically update the property from your expression.

Simple example of using a property:

    Button:
        text: str(self.state)

In this example, we are detecting self.state as a dynamic value. Since the `state` of the button can change at every moment, we are binding this value expression to the state property of the Button. Everytime the button state changed, the text property will be updated.

Since the value is a python expression, you could do something more interesting like:

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

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

## Graphical instructions

The graphical instructions is a special part of the kv language. This concern 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 are inherith from the `Instruction` class. You cannot put any Widget class inside the canvas property.

If you want to do theming, you’ll have the same problem as CSS: you don’t know which rule have been executed before. For our case, the rule are executed in processing order.

If you want to change of a Button is rendered, you can create your own kv, and put 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

It will result a button with a red background, and the label texture in the bottom left.... in addition to all the precedent 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 will be taken.

`kivy.lang.` `Builder`

  Main instance of a `BuilderBase`.

class `kivy.lang.` `BuilderBase`

  Bases: `object`

  Kv object are able to load Kv file or string, return the root object of the file, and inject rules in the rules database.

  `apply`(widget)

    Apply all the Kivy rules matching the widget on the widget.

  `load_file`(filename, **kwargs)

    Insert a file into the Language Builder

    Parameters : | rulesonly: bool, default to False If True, the Builder will raise an exception if you have a root widget inside the definition

  `load_string`(string, **kwargs)

    Insert a string into the Language Builder

    Parameters : | rulesonly: bool, default to False If True, the Builder will raise an exception if you have a root widget inside the definition

  `match`(widget)

    Return the list of the rules matching the widget

class `kivy.lang.` `Parser`(**kwargs)

  Bases: `object`

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

  `load_resource`(filename)

    Load an external resource

  `parse`(content)

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

  `parse_level`(level, lines)

    Parse the current level (level * 4) indentation

  `parse_version`(line)

    Parse the version line. The version line is always #:kivy <version>

  `strip_comments`(lines)

    Remove all comments from lines inplace. Comments need to be on a single line and not at the end of a line. I.e., a line’s first non-whitespace character needs to be a #.