Designing with the Kivy LanguageΒΆ
Let’s start with a little example. First, the Python file named main.py:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | import kivy
kivy.require('1.0.5')
from kivy.uix.floatlayout import FloatLayout
from kivy.app import App
from kivy.properties import ObjectProperty, StringProperty
class Controller(FloatLayout):
'''Create a controller that receives a custom widget from the kv lang file.
Add an action to be called from the kv lang file.
'''
label_wid = ObjectProperty()
info = StringProperty()
def do_action(self):
self.label_wid.text = 'My label after button press'
self.info = 'New info text'
class ControllerApp(App):
def build(self):
return Controller(info='Hello world')
if __name__ in ('__android__', '__main__'):
ControllerApp().run()
|
In this example, we are creating a Controller class, with 2 properties:
- info for receving some text
- label_wid for receving the label widget
In addition, we are creating a do_action() method, that will use both of these properties. It will change the info text, and change text in the label_wid widget.
Executing this application without a corresponding .kv file will work, but nothing will be shown on the screen. This is expected, because the Controller class has no widgets in it, it’s just a FloatLayout. We can create the UI around the Controller class in a file named controller.kv, which will be loaded when we run the ControllerApp. How this is done and what files are loaded is described in the kivy.app.App.load_kv() method.
#:kivy 1.0
<Controller>:
label_wid: my_custom_label
BoxLayout:
orientation: 'vertical'
padding: 20
Button:
text: 'My controller info is : ' + root.info
on_press: root.do_action()
Label:
id: my_custom_label
text: 'My label before button press'
One label and one button in a vertical BoxLayout. Seems very simple. There are 3 things going on here:
Using data from the Controller. As soon as the info property is changed in the controller, the expression text: 'My controller info is : ' + root.info will automatically be re-evaluated, changing the text in the Button.
Giving data to the Controller. The expression id: my_custom_label is assigning the created Label the id of my_custom_label. Then, using my_custom_label in the expression label_wid: my_custom_label gives the instance of that Label widget to your Controller.
Creating a custom callback in the Button using the Controller‘s on_press method.
root and self are reserved keywords, useable anywhere. root represents the top widget in the rule and self represents the current widget.
You can use any id declared in the rule the same as root and self. For example, you could do this in the on_press():
Button: on_press: root.do_action(); my_custom_label.font_size = 18
And that’s that. Now when we run main.py, controller.kv will be loaded so that the Button and Label will show up and respond to our touch events.