5. BoxLayout

In the previous examples, BoxLayout has been used. Now, we will go over it, in a more detailed fashion.

---

These are the files in a folder. There is a Python file and 5 Kivy language files. However, only one kv file will be called, by the Python file, at a time.

---

This is the main Python file, which will call a particular kv file, using the load_file function, of the Builder class. Note, we don't have a main kv file as it is not needed.

# helloworld.py

from kivy.uix.boxlayout import BoxLayout
from kivy.lang import Builder
from kivy.app import App

Builder.load_file('helloworld_1.kv')

class MyBox(BoxLayout):
    pass
   
class HelloWorldApp(App):
    def build(self):
        return MyBox()

if __name__=='__main__':
    HelloWorldApp().run()

---

This is the first kv file, and it is similar to that in the previous example. However, the orientation, now, is vertical.

# helloworld_1.kv

<MyBox>:
  orientation: 'vertical'
  Button:
    text: 'B1'
    on_press: print('--> B1')
  Button:
    text: 'B2'
    on_press: print('--> B2')
  Button:
    text: 'B3'
    on_press: print('--> B3')

    

---

It results in 3 buttons arranged vertically, taking the entire space of the layout. Since we didn't specify otherwise, each button is the same size.

---

In the second kv file, spacing is added. This means, that there is a spacing of 50 pixels between the buttons.

# helloworld_2.kv (spacing)

<MyBox>:
    orientation: 'vertical'
    spacing: 50
    Button:
        text: 'B1'
        on_press: print('--> B1')
    Button:
        text: 'B2'
        on_press: print('--> B2')
    Button:
        text: 'B3'
        on_press: print('--> B3')
                        

---

This shows the result of loading the second kv file. For relative comparison, the size of the app window, which is also the layout size in this case, is 800 by 600.

---

Padding adds margins between the layout and its child widgets. Padding is a Python List of 4 elements, referring to the left, top, right, and bottom margins. If Padding is given only 1 value, all margins are the same. If Padding is given only 2 values, the top and bottom are the same as well as the left and right. We see that left margin is the smallest value, in this kv file, and the bottom is the greatest.

# helloworld_3.kv (spacing,padding)

<MyBox>:
    orientation: 'vertical'
    spacing: 50
    padding: [20,40,60,80]
    Button:
        text: 'B1'
        on_press: print('--> B1')
    Button:
        text: 'B2'
        on_press: print('--> B2')
    Button:
        text: 'B3'
        on_press: print('--> B3')
                        

---

This result confirms that the margins have been correctly added.

---

Now the spacing and padding are removed, to see how pos_hint and size_hint work. size_hint is a Python List of 2 values corresponding to x and y and is only a relative scale. Button3 has an x-value that is twice the other buttons so it is twice the width as the other buttons. For the y, button2 has a y-value that is twice the other buttons so it is twice the height as the others. pos_hint is a Python Dictionary, of x- and y-values. However in vertical BoxLayout orientation, only the x element can be used. The x-value can refer to the leftmost point of widget, 'x', center point of widget, 'center-x', or rightmost point of widget, 'right'. The number are relative to the layout size, from 0 to 1.

# helloworld_4.kv 
# pos_hint, size_hint

<MyBox>:
    orientation: 'vertical'
    Button:
        text: 'B1'
        on_press: print('--> B1')
        pos_hint: {'x' : .1}
        size_hint: [.2,1]
    Button:
        text: 'B2'
        on_press: print('--> B2')
        pos_hint: {'center_x' : .3}
        size_hint: [.2,2]
    Button:
        text: 'B3'
        on_press: print('--> B3')
        pos_hint: {'right': 1}
        size_hint: [.4,1]
                        

---

For the particular kv file, we get this result with some annotations added. For button 1, we set 'x' at .1 (10%). For button 2, we set 'center_x' at .3 (30%). For button 3, we set 'right' at 1 (100%).

---

This Kivy file uses the same values as before except spacing and padding are added.

# helloworld_5.kv (spacing,padding)
# pos_hint, size_hint

<MyBox>:
    orientation: 'vertical'
    spacing: 50
    padding: [20,40,60,80]
    Button:
        text: 'B1'
        on_press: print('--> B1')
        pos_hint: {'x' : .1}
        size_hint: [.2,1]
    Button:
        text: 'B2'
        on_press: print('--> B2')
        pos_hint: {'center_x' : .3}
        size_hint: [.2,2]
    Button:
        text: 'B3'
        on_press: print('--> B3')
        pos_hint: {'right': 1}
        size_hint: [.4,1]
                        

---

Now we can see the margins are added, and there is spacing between the widgets. There are other properties in the BoxLayout, but these form the foundation, and will give the results you want, most of the time.

---