Kivy Language¶

Kivy Language — Kivy 2.3.0 documentation

Kivy Language¶

Jump to API ⇓

---

Module: kivy.lang

Added in 1.0.0

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.
Kivy语言是一种专门用于描述用户界面及其交互的语言。你可以将它与Qt的QML（http://qt.nokia.com）进行比较，但我们在其中加入了一些新概念，如规则定义（这与你可能了解的CSS中的概念有些相似）、模板化等。

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.
在1.7.0版本中有所改动：Builder不再实时执行画布表达式。它会先打包所有需要执行的表达式，然后在分发输入后、绘制帧之前执行它们。如果你想要强制执行画布绘制，只需调用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.
此外，Kivy语言还包含了一个实验性的性能分析工具。你可以通过设置环境变量KIVY_PROFILE_LANG=1来激活它。激活后，它将生成一个名为builder_stats.html的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 behavior 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).
规则类似于CSS规则。规则应用于你的控件树中的特定控件（或其类），并以某种方式修改它们。你可以使用规则来指定交互行为，或者将它们应用于的控件添加图形表示。你可以通过使用cls属性（例如cls=MyTestWidget）来定位特定类的控件（类似于CSS中的类概念）。

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.
你可以使用该语言来创建整个用户界面。一个kv文件最多只能包含一个根控件。

Dynamic Classes    动态类

(introduced in version 1.7.0) Dynamic classes let you create new widgets and rules on-the-fly, without any Python declaration.
（在1.7.0版本中引入）动态类允许你即时创建新的控件和规则，而无需任何Python声明。

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.
（在1.0.5版本中引入，从1.7.0版本开始弃用）模板用于填充应用程序的部分内容，例如设置列表的样式（例如，左侧图标，右侧文本）。现在它们已被动态类取代。

Syntax of a kv File¶    kv文件的语法

---

A Kivy language file must have .kv as filename extension.
Kivy语言文件必须以.kv作为文件扩展名。

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头部开始，其中version必须替换为你正在使用的Kivy语言版本。目前，请使用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 creating 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 widget.
在这里，prop1 和 prop2 是 ClassName 类的属性，而 prop3 是 AnotherClass 类的属性。如果某个控件（widget）没有给定名称的属性，那么将会自动为这个控件创建一个 ObjectProperty，并将其添加到该控件中。

AnotherClass will be created and added as a child of the ClassName instance.
AnotherClass 的实例将会被创建，并作为 ClassName 实例的子控件被添加。

• 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.
  缩进是很重要的，并且必须保持一致。空格的数量必须是第一行缩进所用空格数量的倍数。推荐使用空格进行缩进：不建议将制表符（tabs）和空格混合使用，因为这可能会导致缩进解释不一致的问题。

• The value of a property must be given on a single line (for now at least).
  属性值必须（至少目前是这样）在同一行内给出。

• Keep class names capitalized to avoid syntax errors.
  请将类名大写以避免语法错误。

• The canvas property is special: you can put graphics instructions in it to create a graphical representation of the current class.
  canvas 属性是特殊的：你可以在其中放置图形指令，以创建当前类的图形表示。

Here is a simple example of a kv file that contains a root widget:
下面是一个包含根控件的kv文件的简单示例的翻译：

#: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.
在1.7.0版本中进行了更改：缩进不再局限于4个空格。空格的数量必须是第一行缩进所用空格数量的倍数。

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.
load_file()和load_string()方法都会返回你的kv文件/字符串中定义的根控件。它们还会将任何类和模板定义添加到Factory中，以便后续使用。

Value Expressions, on_property Expressions, ids, and Reserved Keywords¶
值表达式、on_property表达式、ids和保留关键字

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.
当你指定一个属性的值时，该值会被评估为一个Python表达式。这个表达式可以是静态的或动态的，这意味着值可以使用其他属性的值，通过保留关键字来实现。

self

        The keyword self references the “current widget instance”:
        关键字 self 引用的是“当前控件实例”。

在Kivy的kv语言中，当你在定义控件的属性或者绑定事件时，self 关键字用于指代当前正在被定义或操作的控件实例。这使得你可以访问该控件的其他属性或方法，以及触发该控件的事件等。不过，需要注意的是，在kv语言中直接使用 self 的情况并不像在Python代码中那样普遍，因为kv语言主要是用于声明式的界面描述，而不是编写程序逻辑。但在某些上下文中，如事件绑定或动态属性更新时，self 仍然是一个有用的引用。

然而，在kv文件中直接写代码（如Python表达式）时，你更多地是通过属性名或预留的关键字（如root）来引用其他控件或控件的属性，而不是直接使用 self。self 的概念在Kivy的Python后端代码中更为常见，用于在类的方法中引用类的实例。但在kv文件中，你通常不需要（也不应该）显式地使用 self，因为kv语言的语法和上下文已经隐含了这一点。

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):
这个关键字仅在规则定义中可用，并且它代表规则的根控件（即该规则的第一个实例）。

<MyWidget>:
    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.
这个关键字总是引用你的应用程序实例。它相当于在Python中调用kivy.app.App.get_running_app()。

Label:
    text: app.name

args

        This keyword is available in on_<action> callbacks. It refers to the arguments passed to the callback.
这个关键字在on_<action>回调函数中可用。它指的是传递给回调函数的参数。

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

Changed in version 2.1.0: f-strings are now parsed in value expressions, allowing to bind to the properties that they contain.
在2.1.0版本中进行了更改：现在，在值表达式中会解析f-string（格式化字符串字面量），从而允许将值绑定到它们所包含的属性上。

ids¶

---

Class definitions may contain ids which can be used as a keywords:
类定义中可以包含ids，这些ids可以用作关键字来引用类内部定义的小部件或元素。

<MyWidget>:
    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).
请注意，id 不会在小部件实例中直接可用：它仅用于外部引用。id 是对小部件的弱引用（weakref），而不是小部件本身。要访问小部件本身，可以使用 <id>.__self__（在这个例子中就是 btn1.__self__）。

When the kv file is processed, weakrefs to all the widgets tagged with ids are added to the root widget’s ids dictionary. In other words, following on from the example above, the buttons state could also be accessed as follows:
当处理 .kv 文件时，所有带有 ids 标签的小部件的弱引用会被添加到根小部件的 ids 字典中。换句话说，继续上面的例子，按钮的状态也可以通过以下方式访问：

widget = MyWidget()
state = widget.ids["btn1"].state

# Or, as an alternative syntax,
state = widget.ids.btn1.state

Note that the outermost widget applies the kv rules to all its inner widgets before any other rules are applied. This means if an inner widget contains ids, these ids may not be available during the inner widget’s __init__ function.
请注意，最外层的小部件会在应用任何其他规则之前，将其kv规则应用于其内部的所有小部件。这意味着，如果内部小部件包含ids，则在内部小部件的__init__函数执行期间，这些ids可能不可用。

Valid expressions¶  有效的表达式¶

There are two places that accept python statements 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).
在.kv文件中，有两个地方可以接受Python语句：一个是在属性之后，这会将属性的值设置为表达式的结果（如上面所示的按钮文本）；另一个是在on_property之后，这会在属性更新时执行该语句（如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').
在前一种情况下，expression（表达式）只能跨越单行，不能使用换行转义扩展到多行，并且必须返回一个值。一个有效的表达式示例是text: self.state and ('up' if self.state == 'normal' else 'down')。

In the latter case, multiple single line statements are valid, including those 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).
当你使用Kivy语言时，你可能会注意到我们在幕后做了一些工作来自动使事情正常运作。你应该知道，Properties（属性）实现了Observer Design Pattern（观察者设计模式）。这意味着你可以将自己的函数绑定到属性上，以便在属性值发生变化时调用该函数（即你被动地“观察”属性以检测潜在的变化）。

The Kivy language detects properties in your value expression and will create callbacks to automatically update the property via your expression when changes occur.
Kivy语言会在你的value表达式中检测属性，并创建回调，以便在发生变化时通过你的表达式自动更新属性。

Here’s a simple example that demonstrates this behavior:
以下是一个简单示例，展示了这种行为：

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!’.

More precisely, the kivy language parser detects all substrings of the form X.a.b where X is self or root or app or a known id, and a and b are properties: it then adds the appropriate dependencies to cause the constraint to be reevaluated whenever something changes. For example, this works exactly as expected:

<IndexedExample>:
    beta: self.a.b[self.c.d]

However, due to limitations in the parser which hopefully may be lifted in the future, the following doesn’t work:

<BadExample>:
    beta: self.a.b[self.c.d].e.f

indeed the .e.f part is not recognized because it doesn’t follow the expected pattern, and so, does not result in an appropriate dependency being setup. Instead, an intermediate property should be introduced to allow the following constraint:

<GoodExample>:
    alpha: self.a.b[self.c.d]
    beta: self.alpha.e.f

In addition, properties in python f-strings are also not yet supported:

<FStringExample>:
    text: f"I want to use {self.a} in property"

Instead, the format() method should be used:

<FormatStringExample>:
    text: "I want to use {} in property".format(self.a)

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 separate 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 instantiated, with the default value “world”. Lists, tuples, dictionaries and strings are supported.

Let’s illustrate the usage of these 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 its 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 instantiate 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. These 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 references the id
           # mywidget
   

2. 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, if it changes value, ctxkey
           # will not be updated
   

Template definitions also replace any similarly named definitions in their entirety and thus do not support inheritance.

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.

Redefining a widget’s property style¶

Similar to redefining style, sometimes we would like to inherit from a widget, keep all its KV defined styles, except for the style applied to a specific property. For example, we would like to inherit from a Button, but we would also like to set our own state_image, rather then relying on the background_normal and background_down values. We can achieve this by prepending a dash (-) before the state_image property name in the .kv style definition.

In myapp.py:

class MyWidget(Button):
    new_background = StringProperty('my_background.png')

and in my.kv:

<MyWidget>:
    -state_image: self.new_background

MyWidget will now have a state_image background set only by new_background, and not by any previous styles that may have set state_image.

Note

Although the previous rules are cleared, they are still applied during widget construction and are only removed when the new rule with the dash is reached. This means that initially, previous rules could be used to set the property.

Order of kwargs and KV rule application¶

Properties can be initialized in KV as well as in python. For example, in KV:

<MyRule@Widget>:
    text: 'Hello'
    ramp: 45.
    order: self.x + 10

Then MyRule() would initialize all three kivy properties to the given KV values. Separately in python, if the properties already exist as kivy properties one can do for example MyRule(line=’Bye’, side=55).

However, what will be the final values of the properties when MyRule(text=’Bye’, order=55) is executed? The quick rule is that python initialization is stronger than KV initialization only for constant rules.

Specifically, the kwargs provided to the python initializer are always applied first. So in the above example, text is set to ‘Bye’ and order is set to 55. Then, all the KV rules are applied, except those constant rules that overwrite a python initializer provided value.

That is, the KV rules that do not creates bindings such as text: ‘Hello’ and ramp: 45., if a value for that property has been provided in python, then that rule will not be applied.

So in the MyRule(text=’Bye’, order=55) example, text will be ‘Bye’, ramp will be 45., and order, which creates a binding, will first be set to 55, but then when KV rules are applied will end up being whatever self.x + 10 is.

Changed in version 1.9.1: Before, KV rules always overwrote the python values, now, python values are not overwritten by constant rules.

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.9.0.

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)

APIHide Description ⇑

class kivy.lang.BuilderBase¶

Bases: builtins.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, ignored_consts={}, rule_children=None, dispatch_kv_post=False)¶

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

Parameters:

widget: Widget

The widget whose class rules should be applied to this widget.

ignored_consts: set

A set or list type whose elements are property names for which constant KV rules (i.e. those that don’t create bindings) of that widget will not be applied. This allows e.g. skipping constant rules that overwrite a value initialized in python.

rule_children: list

If not None, it should be a list that will be populated with all the widgets created by the kv rules being applied.

Changed in version 1.11.0.

dispatch_kv_post: bool

Normally the class Widget dispatches the on_kv_post event to widgets created during kv rule application. But if the rules are manually applied by calling apply(), that may not happen, so if this is True, we will dispatch the on_kv_post event where needed after applying the rules to widget (we won’t dispatch it for widget itself).

Defaults to False.

Changed in version 1.11.0.

apply_rules(widget, rule_name, ignored_consts={}, rule_children=None, dispatch_kv_post=False)¶

Search all the rules that match the name rule_name and apply them to widget.

New in version 1.10.0.

Parameters:

widget: Widget

The widget to whom the matching rules should be applied to.

ignored_consts: set

A set or list type whose elements are property names for which constant KV rules (i.e. those that don’t create bindings) of that widget will not be applied. This allows e.g. skipping constant rules that overwrite a value initialized in python.

rule_children: list

If not None, it should be a list that will be populated with all the widgets created by the kv rules being applied.

Changed in version 1.11.0.

dispatch_kv_post: bool

Normally the class Widget dispatches the on_kv_post event to widgets created during kv rule application. But if the rules are manually applied by calling apply(), that may not happen, so if this is True, we will dispatch the on_kv_post event where needed after applying the rules to widget (we won’t dispatch it for widget itself).

Defaults to False.

Changed in version 1.11.0.

classmethod create_from(builder)¶

Creates a instance of the class, and initializes to the state of builder.

Parameters:

builder – The builder to initialize from.

Returns:

A new instance of this class.

load_file(filename, encoding='utf8', **kwargs)¶

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.

encoding: File character encoding. Defaults to utf-8,

load_string(string, **kwargs)¶

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.

filename: str, defaults to None

If specified, the filename used to index the kv rules.

The filename parameter can be used to unload kv strings in the same way as you unload kv files. This can be achieved using pseudo file names e.g.:

Build.load_string("""
    <MyRule>:
        Label:
            text="Hello"
""", filename="myrule.kv")

can be unloaded via:

Build.unload_file("myrule.kv")

match(widget)¶

Return a list of ParserRule objects matching the widget.

match_rule_name(rule_name)¶

Return a list of ParserRule objects matching the widget.

sync()¶

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)¶

Create a specialized template using a specific context.

New in version 1.0.5.

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

unbind_property(widget, name)¶

Unbind the handlers created by all the rules of the widget that set the name.

This effectively clears all the rules of widget that take the form:

name: rule

For example:

w = Builder.load_string('''
Widget:
    height: self.width / 2. if self.disabled else self.width
    x: self.y + 50
''')
w.size
[100, 100]
w.pos
[50, 0]
w.width = 500
w.size
[500, 500]
Builder.unbind_property(w, 'height')
w.width = 222
w.size
[222, 500]
w.y = 500
w.pos
[550, 500]

New in version 1.9.1.

unbind_widget(uid)¶

Unbind all the handlers created by the KV rules of the widget. The kivy.uix.widget.Widget.uid is passed here instead of the widget itself, because Builder is using it in the widget destructor.

This effectively clears all the KV rules associated with this widget. For example:

w = Builder.load_string('''
Widget:
    height: self.width / 2. if self.disabled else self.width
    x: self.y + 50
''')
w.size
[100, 100]
w.pos
[50, 0]
w.width = 500
w.size
[500, 500]
Builder.unbind_widget(w.uid)
w.width = 222
w.y = 500
w.size
[222, 500]
w.pos
[50, 500]

New in version 1.7.2.

unload_file(filename)¶

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.

exception kivy.lang.BuilderException(context, line, message, cause=None)¶

Bases: ParserException

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

class kivy.lang.Observable¶

Bases: kivy.event.ObjectWithUid

Observable is a stub class defining the methods required for binding. EventDispatcher is (the) one example of a class that implements the binding interface. See EventDispatcher for details.

New in version 1.9.0.

bind(self, **kwargs)¶

fbind(self, name, func, *largs, **kwargs)¶

See EventDispatcher.fbind().

Note

To keep backward compatibility with derived classes which may have inherited from Observable before, the fbind() method was added. The default implementation of fbind() is to create a partial function that it passes to bind while saving the uid and largs/kwargs. However, funbind() (and unbind_uid()) are fairly inefficient since we have to first lookup this partial function using the largs/kwargs or uid and then call unbind() on the returned function. It is recommended to overwrite these methods in derived classes to bind directly for better performance.

Similarly to EventDispatcher.fbind(), this method returns 0 on failure and a positive unique uid on success. This uid can be used with unbind_uid().

funbind(self, name, func, *largs, **kwargs)¶

See fbind() and EventDispatcher.funbind().

unbind(self, **kwargs)¶

unbind_uid(self, name, uid)¶

See fbind() and EventDispatcher.unbind_uid().

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

Bases: builtins.object

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

parse(content)¶

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

parse_level(level, lines, spaces=0)¶

Parse the current level (level * spaces) indentation.

strip_comments(lines)¶

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 #.

exception kivy.lang.ParserException(context, line, message, cause=None)¶

Bases: Exception

Exception raised when something wrong happened in a kv file.

• Builder
  • Builder
  • BuilderBase
    • BuilderBase.apply()
    • BuilderBase.apply_rules()
    • BuilderBase.create_from()
    • BuilderBase.load_file()
    • BuilderBase.load_string()
    • BuilderBase.match()
    • BuilderBase.match_rule_name()
    • BuilderBase.sync()
    • BuilderBase.template()
    • BuilderBase.unbind_property()
    • BuilderBase.unbind_widget()
    • BuilderBase.unload_file()
  • BuilderException
  • Observable
    • Observable.bind()
    • Observable.fbind()
    • Observable.funbind()
    • Observable.unbind()
    • Observable.unbind_uid()
• Parser
  • Parser
    • Parser.parse()
    • Parser.parse_level()
    • Parser.strip_comments()
  • ParserException