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.
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)
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.
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'
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.
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!’
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.
Main instance of a 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 all the Kivy rules matching the widget on the widget.
Insert a file into the Language Builder
Parameters : |
|
---|
Insert a string into the Language Builder
Parameters : |
|
---|
Return the list of the rules matching the widget
Bases: object
Create a Parser object to parse a Kivy file or Kivy content.
Load an external resource
Parse the content of a Parser file, and return a list of root objects.
Parse the current level (level * 4) indentation
Parse the version line. The version line is always #:kivy <version>
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 #.