Basisoverzicht Kivy

Dus jij wilt met Python en Kivy een mooie app maken voor de Amiga robot van Farm-ng? Dan zit je op de goede pagina!

Setup

Hier volgt een stappenplan. Hier zitten gelijk deployment configuraties en syntax highlighting extensies bij:

1. Installeer PyCharm.
2. Maak een repository door de Kivy Example template te gebruiken.
3. Installeer de extensie voor Kivy auto-completion en syntax highlighting volgens deze pagina.
4. Volg dit stappenplan om de app lokaal op je computer en op de robot zelf uit te kunnen voeren.

Vervolgens is het essentieel dat je de manifest.json goed instelt. Daarvoor refereer ik naar de pagina over het dashboard.

LET OP!!!

PyCharm markeert de ‘src’ map niet automatisch als ‘sources’. Doe dit handmatig, zoals hier beschreven.

De .kv bestanden

Een layout in Kivy volgt het volgende format:

<LoginScreen>:  # every class in your app can be represented by a rule like
                # this in the kv file
    GridLayout: # this is how you add your widget/layout to the parent
                # (note the indentation).
        rows: 2 # this how you set each property of your widget/layout

Een voorbeeld van zo’n bestand:

Layouts kunnen zowel in code als in de .kv bestanden gedefineerd worden. Het scheiden van layout en logica is een goed principe, en dus raad ik aan om layouts in aparte .kv bestanden te maken. Hier een start van zo’n dergelijk bestand:

RelativeLayout:  
    TabbedPanel:  
        pos_hint: {"x": 0.0, "top": 1.0}  
        do_default_tab: False  
        id: tab_root  
  
        TabbedPanelItem:  
            text: 'Counter'  
            BoxLayout:  
                Label:  
                    id: counter_label  
                    text: "Tic: 0"  
                    font_size: 40

Kivy werkt met indenting net zoals Python. Wat je hier ziet is dus een duidelijke hiërarchie.

Dit is de UI die hierbij hoort. Er zijn enkele elementen die je waarschijnlijk gelijk herkent!

Layouts

Om widgets een plek te geven op het scherm maak je gebruik van zogenoemde layouts. Kivy beschikt over meerdere layouts. Momenteel zijn dat de klassiekers:

• Box Layout
• Grid Layout
• Stack Layout
• Anchor Layout
• Float Layout
• Relative Layout

Afbeeldingen bij layouts

Events

Het zou fijn zijn als er iets gebeurt op het moment dat ik op een knop klik. Daarvoor heeft men ‘events’ bedacht. Kivy is ‘mostly-event based’. Het verloop van jouw app is afhankelijk van events.

De werking hiervan is erg voor de hand liggen en is te snappen aan de hand van een enkel code voorbeeld. Daarom raad ik iedereen aan om deze & deze pagina te lezen waardoor de werking hiervan gelijk duidelijk is.

Properties

Mocht je al ervaring hebben met frameworks als WPF, dan weet je vast wat een Observable Property is. Dat is een waarde die bij verandering een callback kan uitvoeren. Stel bijvoorbeeld dat wij waarde x aanpassen, willen we misschien ook dat dit op het scherm aangepast wordt!

Gebruik properties

Bij het declareren van variables in klassen in Python ben je waarschijnlijk de volgende syntax gewend:

class MyClass(object):
    def __init__(self):
        super(MyClass, self).__init__()
        self.numeric_var = 1

In Kivy kunnen wij een property zo declareren:

class MyClass(EventDispatcher):
    numeric_var = NumericProperty(1)

Let op dat het dus op klasseniveau gedeclareerd is!

Ingebouwde properties

Nu waren de ontwikkelaars van Kivy dermate goedgezind dat ze voor ons al heel wat geïmplementeerd hebben! Sterker nog, de volgende properties bestaan al:

Property Type	Uitleg
StringProperty	Tekst!
NumericProperty	Een nummer! Moet int, float, of een string met geldige numerieke waarde zijn.
BoundedNumericProperty	Een nummer met een minimum en/of een maximum!
ObjectProperty	?
DictProperty	Property voor een dictionary! Let op: maakt een shallow copy van de items.
ListProperty	Property voor een lijst! Let op: maakt een shallow copy van de items.
OptionProperty	Handig voor bijvoorbeeld een Dropdown menuutje. Moet altijd een standaardwaarde hebben. Als er een waarde geselecteerd wordt die niet in de lijst van mogelijke waarden stond krijg je een ValueError.
AliasProperty	Laat je snel je eigen property maken door een getter en setter te specificeren.
BooleanProperty	Boolean! true of false.
ReferenceListProperty	Laat je meerdere properties als tuple behandelen. Zo kan je een pos property maken voor een x & y property.
ColorProperty	Kleur in string formaat. In rrggbb, rrggbbaa, of met kleurnaam (zoals ‘red’ of ‘green’).
ConfigParserProperty	?

Configuratie App

Je app kan je configureren door het Config object en door environment variabelen. Ik ga in deze paragraaf alleen in op het Config object.

Je kan in Kivy heel veel configureren, waaronder de maxfps & double_tap_distance.

De standaard is om configuraties boven in je main.py te zetten voordat andere code uitgevoerd wordt.

Waarden lezen:

from kivy.config import Config
Config.getint('kivy', 'show_fps')

Waarden instellen (en opslaan):

Config.set('postproc', 'retain_time', '50')
Config.write() # Optional. Only if wanted.

Een voorbeeld van configuratie in code is als volgt:

from kivy.config import Config
 
Config.set("graphics", "resizable", False)  
Config.set("graphics", "width", "1280")  
Config.set("graphics", "height", "800")  
Config.set("graphics", "fullscreen", "false")  
Config.set("input", "mouse", "mouse,disable_on_activity")  
Config.set("kivy", "keyboard_mode", "systemanddock")  
Config.set('modules', 'touchring', '')  
Config.set('modules', 'monitor', '')

Configuratie omgeving

Pas op!

Ga niet lopen spelen met waardes hierin! Als je iets MOET aanpassen vraag jezelf dan af of dat is omdat je een slecht ontwerp hebt of dat je daadwerkelijk gedwongen bent om dit te gebruiken.

Wil je verder invloed uit oefenen op je Kivy omgeving, zoals kiezen welke framework verantwoordelijk is voor het renderen van tekst, kijk dan hier.

Modules

Modules zijn klassen die geladen worden bij het starten van een Kivy applicatie. Dit zijn de huidig ingebouwde modules:

Module	Beschrijving
touchring	Draw a circle around each touch.
monitor	Add a red topbar that indicates the FPS and a small graph indicating input activity.
keybinding	Bind some keys to actions, such as a screenshot.
recorder	Record and playback a sequence of events.
screen	Emulate the characteristics (dpi/density/resolution) of different screens.
inspector	Examines your widget hierarchy and widget properties.
webdebugger	Realtime examination of your app internals via a web browser.
joycursor	Navigate in your app with a joystick.
showborder	Show widget’s border.

Ik raad je bij het ontwerpen van de UI aan om de inspector te gebruiken. Bij touchscreen met lichte defecten en/of afwijkingen is touchring ook erg nuttig.

Mocht je aan het configureren zijn voor performance, is monitor ook heel handig. Hierbij heb ik wel de notities dat de maxfps instelling in je configuratie niet 100% accuraat is en dat er een kleine speling in zit. Zet deze aub ook niet op 0 of een negatief getal, want dit haalt de limiet weg en gebruikt vervolgens 100% CPU usage.

De inspector

De inspector in Kivy geeft je informatie over de hiërarchie in je huidige scene, en laat je bij widgets zien welke waardes ze hebben. Dit is een ontzettende nuttige tool bij het ontwerpen & ontwikkelen van je UI.

De inspector is te togglen met Ctrl + e.

Voor het activeren kan je deze oneliner gebruiken (of kijken bij Het activeren van modules):

Config.set('modules', 'inspector', '')

Voor details zie hier.

Het activeren van modules

Het activeren van modules is op twee manieren mogelijk:

1. Het configureren van je .ini bestand.
2. Het specificeren in je code.

Beide opties gebruiken je configuratie.

Een voorbeeld van een .ini bestand (in HOME/.kivy/config.ini):

[modules]
# uncomment to activate
touchring =
# monitor =
# keybinding =

Een voorbeeld van het specificeren in je code:

import kivy
kivy.require('1.0.8')
 
# Activate the touchring module
from kivy.config import Config
Config.set('modules', 'touchring', '')

Eigen modules

Het is ook mogelijk om je eigen modules te maken. Zie hier hoe.

Texture atlas

Mocht je veel afbeeldingen gebruiken in je applicatie raad ik je aan om een texture atlas te gebruiken. Een texture atlas is een grote afbeelding die al jouw afbeelding resources bevat! Dit heeft als voordeel dat er maar een keer een afbeelding in het geheugen geladen hoeft te worden.

De documentatie is hier te vinden.