Designing with the Kv language

This recipe will give you a first look at the widgets' distribution and their interaction.

Getting ready

This recipe will use two common widgets, just for reference; again we'll be looking at the Button and TextInput fields. Also, a common kind of layout is BoxLayout, which controls the distribution of objects in the interface.

How to do it…

This recipe works by performing the following steps:

1. First, the KV file:

   <Controller>:
       label_wid: my_custom_label
   
       BoxLayout:
           orientation: 'horizontal'
           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'

2. Next, the Python code:

   import kivy
   kivy.require('1.8.0')
   
   from kivy.uix.floatlayout import FloatLayout
   from kivy.app import App
   from kivy.properties import ObjectProperty, StringProperty
   
   class Controller(FloatLayout):
   
       label_wid = ObjectProperty()
       info = StringProperty()
   
       def do_action(self):
           self.label_wid.text = 'Button pressed'
           self.info = 'Bye'
   
   class e8App(App):
       def build(self):
           return Controller(info='Hello world')
   if __name__ == '__main__':
       e8App().run()

How it works…

If we are designing with the Kv language, let's see it in detail. In the first line:

<Controller>:

We are given the rule Controller, so remember that you are going to need a class Controller in your Python code. The second line is:

label_wid: my_custom_label

This code line gives defines the label for this rule from a reference to the Label. The third line is:

BoxLayout:

We start the definition of the properties for the layout. In the fourth and fifth lines:

    orientation: 'horizontal'
    padding: 20

We give values to the properties: in this case, horizontal to the orientation and 20 to the padding (the empty space beyond the border of the window). The sixth, seventh, and eighth lines are:

Button:
    text: 'My controller info is: ' + root.info
    on_press: root.do_action()

This is the definition for the button. Here is the most important part of the designing with the Kv language: the order in which it appears in the code is the same as that in which the widgets are arranged in the layout, so the button will be the leftmost of all the widgets that we will use. The final part of the code is the definition of the Label:

Label:
    id: my_custom_label
    text: 'My label before button press'

There's more…

An interesting modification can be done to the following fourth line of the KV file:

orientation: 'horizontal'

To change the orientation of BoxLayout from horizontal to vertical, we can change the preceding line to the following line:

orientation: 'vertical'

It will have the same functionality, but the button will be above the label.

See also

If you want more details about widgets and layouts, see the recipes in Chapter 4 , Widgets.