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.
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 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.
- Templates
- (introduced in version 1.0.5.) Templates will be used to populate parts of your application, such as a list’s content. If you want to design the look of an entry in a list (icon on the left, text on the right), you will use a template for that.
Syntax of a kv File¶
A Kivy language file must have .kv as filename 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 here
The content can contain rule definitions, a root widget 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 create a template
[TemplateName@BaseClass1,BaseClass2]:
# .. definitions ..
Regardless of whether it’s a rule, root widget 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 4 spaces. Tabs are not allowed.
- 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'
Value 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
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; The id attribute will be not used.
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 software 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. This concerns 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: You don’t know which rules have been executed before. 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 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
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.
Templates¶
New in version 1.0.5.
Syntax of template¶
Using a template in Kivy require 2 things :
- a context to pass for the context (will be ctx inside template)
- 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 more easy to use. So, we’ll create a template that require 2 entry in the context: a image filename and a title
[IconItem@BoxLayout]:
Image:
source: ctx.image
Label:
text: ctx.title
Then in Python, you can create instanciate the template with
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 another 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 screen into kv lang, you have lot of redefinition. In our example, we’ll create a Toolbar, based on a BoxLayout, and put many Image that will react to on_touch_down:
<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:
nput: '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 side 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
source: 'data/%s.png' % ctx.image
size: self.texture_size
size_hint: None, None
# Now, we are using the ctx for the variable part of the template
on_touch_down: self.collide_point(*args[1].pos) and self.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:
you cannot use references other than “root”:
<MyRule>: Widget: id: mywidget value: 'bleh' Template: ctxkey: mywidget.value # << fail, this reference mywidget idall the dynamic part will be not 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
Lang Directives¶
You can use directive to control part of the lang files. Directive is done with a comment line starting with:
#:<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 class 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
- kivy.lang.Builder = <kivy.lang.BuilderBase object at 0xce95f0>¶
Main instance of a BuilderBase.
- class kivy.lang.BuilderBase¶
Bases: object
Builder is responsible for creating a Parser for parsing a kv file, merging the results to its internal rules, templates, etc.
By default, Builder is the global Kivy instance used in widgets, that you can use to load other kv file in addition to the default one.
- apply(widget)¶
Search all the rules that match the widget, and apply them.
- 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 a list of ParserRule matching the widget.
- template(*args, **ctx)¶
Create a specialized template using a specific context. .. versionadded:: 1.0.5
With template, you can construct custom widget from a kv lang definition by giving them a context. Check Template usage.
- unload_file(filename)¶
Unload all rules associated to a previously imported file.
New in version 1.0.8.
Warning
This will not remove rule or template already applied/used on current widget. It will act only for the next widget creation or template invocation.
- class kivy.lang.BuilderException(context, line, message)¶
Bases: kivy.lang.ParserException
Exception raised when the Builder failed to apply a rule on a widget.
- class kivy.lang.Parser(**kwargs)¶
Bases: 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)¶
Parse the current level (level * 4) 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 #.
- class kivy.lang.ParserException(context, line, message)¶
Bases: exceptions.Exception
Exception raised when something wrong happened in a kv file.