Kv language — Kivy 2.3.1 documentation
Guides
Garden
API Reference
PDF
Wiki
Version
Quick search
Gallery of Examples
Gallery
3D Rotating Monkey Head
Widget animation
Suite of Application Builders
Application example using build() + return
Application built from a .kv file
Application from a .kv in a Template Directory
Camera Example
Bezier Example
Canvas stress
Circle Example
FBO Canvas
Line (SmoothLine) Experiment
Lines Extended Demo
Mesh test
Multitexture Example
Repeat Texture on Resize
Rotation Example
Stencil demo
Tesselate Demonstration
Texture Wrapping and Coordinates Example
Shuffled Camera Feed Puzzle
Kivy Catalog
Multistroke Recognition Database Demonstration
Basic Picture Viewer
Live Shader Editor
Showcase of Kivy Features
Touch Tracer Line Drawing Demonstration
Getting Started
Introduction
Installing Kivy
A first App
Properties
Kv Design Language
Events
Non-widget stuff
Layouts
Drawing
Packaging
Diving in
Kivy Project
Philosophy
Contribution Guidelines
FAQ
Programming Guide
Kivy Basics
Controlling the environment
Configure Kivy
Architectural Overview
Events and Properties
Input management
Widgets
Graphics
Kv language
Integrating with other Frameworks
Packaging your application
Package licensing
Tutorials
Pong Game Tutorial
A Simple Paint App
Crash Course
API Reference
Kivy framework
Low level Metrics
Animation
Application
Atlas
Kivy Base
Cache manager
Clock object
Compatibility module for Python 2.7 and >= 3.4
Configuration object
Context
Core Abstraction
Audio
Camera
Clipboard
OpenGL
Image
Spelling
Text
Text Markup
Text layout
Video
Window
Kivy module for binary dependencies.
Effects
Damped scroll effect
Kinetic effect
Opacity scroll effect
Scroll effect
Event dispatcher
Event Manager
Factory object
Garden
Geometry utilities
Gesture recognition
Graphics
BoxShadow
CGL: standard C interface for OpenGL
Graphics compiler
Context management
Context instructions
Framebuffer
GL instructions
Canvas
OpenGL
OpenGL utilities
Scissor Instructions
Shader
Stencil instructions
SVG
Tesselator
Texture
Transformation
Input management
Motion Event Factory
Motion Event
Input Postprocessing
Calibration
Dejitter
Double Tap
Ignore list
Retain Touch
Triple Tap
Motion Event Provider
Providers
Android Joystick Input Provider
Native support for HID input from the linux kernel
Leap Motion - finger only
Native support of Wacom tablet from linuxwacom driver
Native support of MultitouchSupport framework for MacBook (MaxOSX platform)
Mouse provider implementation
Native support for Multitouch devices on Linux, using libmtdev.
Auto Create Input Provider Config Entry for Available MT Hardware (linux only).
TUIO Input Provider
Common definitions for a Windows provider
Input recorder
Motion Event Shape
Interactive launcher
Kivy Language
Builder
Parser
External libraries
DDS File library
GstPlayer
Python mtdev
Asynchronous data loader
Kivy Logging
Metrics
Modules
Console
Inspector
JoyCursor
Keybinding
Monitor module
Recorder module
Screen
Touchring
Web Debugger
Multistroke gesture recognizer
Network support
UrlRequest
Parser utilities
Properties
Resources management
Storage
Dictionary store
JSON store
Redis Store
Support
Tools
Packaging
Pyinstaller hooks
Widgets
Accordion
Action Bar
Anchor Layout
Behaviors
Button Behavior
Code Navigation Behavior
Compound Selection Behavior
Cover Behavior
Drag Behavior
Emacs Behavior
Focus Behavior
Kivy Namespaces
ToggleButton Behavior
Touch Ripple
Box Layout
Bubble
Button
Camera
Carousel
CheckBox
Code Input
Color Picker
Drop-Down List
EffectWidget
FileChooser
Float Layout
Gesture Surface
Grid Layout
Image
Label
Layout
ModalView
PageLayout
Popup
Progress Bar
RecycleBoxLayout
RecycleGridLayout
RecycleLayout
RecycleView
RecycleView Data Model
RecycleView Layouts
RecycleView Views
Relative Layout
reStructuredText renderer
Sandbox
Scatter
Scatter Layout
Screen Manager
ScrollView
Settings
Slider
Spinner
Splitter
Stack Layout
Stencil View
Switch
TabbedPanel
Text Input
Toggle button
Tree View
Video
Video player
VKeyboard
Widget class
Utils
Vector
Weak Method
Weak Proxy
Table Of Contents
Kv language
Concept behind the language
How to load KV
Rule context
Special syntax
Instantiate children
Event Bindings
Extend canvas
Referencing Widgets
Accessing Widgets defined inside Kv lang in your Python code
Dynamic Classes
Re-using styles in multiple widgets
Designing with the Kivy Language
The code goes in py files
The layout goes in controller.kv
More documentation
Kv language
Concept behind the language
As your application grows more complex, it’s common that the construction of
widget trees and explicit declaration of bindings becomes verbose and hard to
maintain. The
KV
Language is an attempt to overcome these shortcomings.
The
KV
language, sometimes called kvlang or the kivy language, allows you to
create your widget tree in a declarative way and to bind widget properties
to each other or to callbacks in a natural manner. It allows for very fast
prototypes and agile changes to your UI. It also facilitates separating
the logic of your application and its User Interface.
How to load KV
There are two ways to load Kv code into your application:
By name convention:
Kivy looks for a Kv file with the same name as your App class in
lowercase, minus “App” if it ends with ‘App’ e.g:
MyApp
->
my
kv
If this file defines a
Root Widget
it will be attached to the App’s
root
attribute and used as the base of the application widget tree.
Builder
You can tell Kivy to directly load a string or a file. If this string or file
defines a root widget, it will be returned by the method:
Builder
load_file
'path/to/file.kv'
or:
Builder
load_string
kv_string
Rule context
A Kv source constitutes of
rules
which are used to describe the content
of a Widget. You can have one
root
rule, and any number of
class
or
template
rules.
The
root
rule is declared by declaring the class of your root widget, without
any indentation, followed by
and will be set as the
root
attribute of the
App instance:
Widget
class
rule, declared by the name of a widget class between
< >
and
followed by
, defines the appearance and behavior of any instance of that
class:
MyWidget
Rules use indentation for delimitation, like Python. Indentation should be
four spaces per level, like the Python style guide
recommends
There are three keywords specific to the Kv language:
app
: always refers to the instance of your application.
root
: refers to the base widget/template in the current rule
self
: always refer to the current widget
Special syntax
There is a special syntax to define values for the whole Kv context.
To access Python modules and classes from kv, use
#:import
#:import name x.y.z
#:import isdir os.path.isdir
#:import np numpy
is equivalent to:
from
x.y
import
as
name
from
os.path
import
isdir
import
numpy
as
np
in Python.
To set a global value, use
#:set
#:set name value
is equivalent to:
name
value
in Python.
Instantiate children
To declare a widget instance of some class as a child widget, just
declare that child inside the rule:
MyRootWidget
BoxLayout
Button
Button
The example above defines that our root widget, an instance of
MyRootWidget
has a child that is an instance of the
BoxLayout
, and that BoxLayout further has two
children, instances of the
Button
class.
The Python equivalent of this code might be:
root
MyRootWidget
()
box
BoxLayout
()
box
add_widget
Button
())
box
add_widget
Button
())
root
add_widget
box
Which you may find less nice, both to read and to write.
Of course, in Python, you can pass keyword arguments to your widgets at
creation to specify their behaviour. For example, to set the number of columns
of a
gridlayout
, we would do:
grid
GridLayout
cols
To do the same thing in kv, you can set properties of the child widget directly
in the rule:
GridLayout
cols
The value is evaluated as a Python expression, and all the properties used in
the expression will be observed, that means that if you had something like this
in Python (this assume
self
is a widget with a
data
ListProperty
):
grid
GridLayout
cols
len
self
data
))
self
bind
data
grid
setter
'cols'
))
To have your display updated when your data change, you can now have just:
GridLayout
cols
len
root
data
Note
Widget names should start with upper case letters while property names
should start with lower case ones. Following the
PEP8 Naming Conventions
is encouraged.
Event Bindings
You can bind to events in Kv using the “:” syntax, that is, associating a
callback to an event:
Widget
on_size
my_callback
()
You can pass the values dispatched by the signal using the
args
keyword:
TextInput
on_text
app
args
])
More complex expressions can be used, like:
pos
self
center_x
self
texture_size
2.
self
center_y
self
texture_size
2.
This expression listens for a change in
center_x
center_y
and
texture_size
. If one of them changes, the expression will be
re-evaluated to update the
pos
field.
You can also handle
on_
events inside your kv language.
For example the TextInput class has a
focus
property whose auto-generated
on_focus
event can be accessed inside the kv language like so:
TextInput
on_focus
args
Extend canvas
Kv lang can be used to define the canvas instructions of your widget like this:
MyWidget
canvas
Color
rgba
.3
.8
.5
Line
points
zip
self
data
self
data
And they get updated when properties values change.
Of course you can use
canvas.before
and
canvas.after
Referencing Widgets
In a widget tree there is often a need to access/reference other widgets.
The Kv Language provides a way to do this using id’s. Think of them as class
level variables that can only be used in the Kv language. Consider the
following:
Button
id
f_but
TextInput
text
f_but
state
Button
id
s_but
TextInput
text
s_but
state
An
id
is limited in scope to the rule it is declared in, so in the
code above
s_but
can not be accessed outside the
rule.
Warning
When assigning a value to
id
, remember that the value isn’t
a string. There are no quotes: good ->
id:
value
, bad ->
id:
'value'
An
id
is a
weakref
to the widget and not the widget itself. As a
consequence, storing the
id
is not sufficient to keep the widget from being
garbage collected. To demonstrate:
label_widget
label_widget
Button
text
'Add Button'
on_press
root
add_widget
label_widget
Button
text
'Remove Button'
on_press
root
remove_widget
label_widget
Label
id
label_widget
text
'widget'
Although a reference to
label_widget
is stored in
MyWidget
, it is not
sufficient to keep the object alive once other references have been removed
because it’s only a weakref.
Therefore, after the remove button is clicked (which removes
any direct reference to the widget) and the window is resized (which calls the
garbage collector resulting in the deletion of
label_widget
), when the add
button is clicked to add the widget back, a
ReferenceError:
weakly-referenced
object
no
longer
exists
will be thrown.
To keep the widget alive, a direct reference to the
label_widget
widget
must be kept. This is achieved using
id.__self__
or
label_widget.__self__
in this case. The correct way to do this would be:
label_widget
label_widget
__self__
Accessing Widgets defined inside Kv lang in your Python code
Consider the code below in my.kv:
# both these variables can be the same name and this doesn't lead to
# an issue with uniqueness as the id is only accessible in kv.
txt_inpt
txt_inpt
Button
id
f_but
TextInput
id
txt_inpt
text
f_but
state
on_text
root
check_status
f_but
In myapp.py:
...
class
MyFirstWidget
BoxLayout
):
txt_inpt
ObjectProperty
None
def
check_status
self
btn
):
'button state is:
{state}
format
state
btn
state
))
'text input text is:
{txt}
format
txt
self
txt_inpt
))
...
txt_inpt
is defined as a
ObjectProperty
initialized
to
None
inside the Class.
txt_inpt
ObjectProperty
None
At this point self.txt_inpt is
None
. In Kv lang this property is updated to
hold the instance of the
TextInput
referenced by the id
txt_inpt
.:
txt_inpt
txt_inpt
From this point onwards,
self.txt_inpt
holds a reference to the widget
identified by the id
txt_input
and can be used anywhere in the class, as in
the function
check_status
. In contrast to this method you could also just pass
the
id
to the function that needs to use it, like in case of
f_but
in the
code above.
There is a simpler way to access objects with
id
tags in Kv using the
ids
lookup object. You can do this as follows:
Label
id
loki
text
'loki: I AM YOUR GOD!'
Button
id
hulk
text
"press to smash loki"
on_release
root
hulk_smash
()
In your Python code:
class
Marvel
BoxLayout
):
def
hulk_smash
self
):
self
ids
hulk
text
"hulk: puny god!"
self
ids
"loki"
text
"loki: >_# alternative syntax
When your kv file is parsed, kivy collects all the widgets tagged with id’s
and places them in this
self.ids
dictionary type property. That means you
can also iterate over these widgets and access them dictionary style:
for
key
val
in
self
ids
items
():
"key=
{0}
, val=
{1}
format
key
val
))
Note
Although the
self.ids
method is very concise, it is generally regarded as
‘best practice’ to use the ObjectProperty. This creates a direct reference,
provides faster access and is more explicit.
Dynamic Classes
Consider the code below:
Button
text
"Hello world, watch this text wrap inside the button"
text_size
self
size
font_size
'25sp'
markup
True
Button
text
"Even absolute is relative to itself"
text_size
self
size
font_size
'25sp'
markup
True
Button
text
"Repeating the same thing over and over in a comp = fail"
text_size
self
size
font_size
'25sp'
markup
True
Button
Instead of having to repeat the same values for every button, we can just use a
template instead, like so:
text_size
self
size
font_size
'25sp'
markup
True
MyBigButton
text
"Hello world, watch this text wrap inside the button"
MyBigButton
text
"Even absolute is relative to itself"
MyBigButton
text
"repeating the same thing over and over in a comp = fail"
MyBigButton
This class, created just by the declaration of this rule, inherits from the
Button class and allows us to change default values and create bindings for all
its instances without adding any new code on the Python side.
Re-using styles in multiple widgets
Consider the code below in my.kv:
Button
on_press
root
text
txt_inpt
text
TextInput
id
txt_inpt
Button
on_press
root
text
txt_inpt
text
TextInput
id
txt_inpt
In myapp.py:
class
MyFirstWidget
BoxLayout
):
def
text
self
val
):
'text input text is:
{txt}
format
txt
val
))
class
MySecondWidget
BoxLayout
):
writing
StringProperty
''
def
text
self
val
):
self
writing
val
Because both classes share the same .kv style, this design can be simplified
if we reuse that style for both widgets. You can do this in .kv as follows.
In my.kv:
Button
on_press
root
text
txt_inpt
text
TextInput
id
txt_inpt
By separating the class names with a comma, all the classes listed in the
declaration will have the same kv properties.
Designing with the Kivy Language
One of the aims of the Kivy language is to
separate the concerns
of presentation and logic. The presentation (layout) side is addressed by your
.kv
file and the logic by your
.py
file.
The code goes in py files
Let’s start with a little example: a Python file named
main.py
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__
==
'__main__'
ControllerApp
()
run
()
In this example, we are creating a Controller class with 2 properties:
info
for receiving some text
label_wid
for receiving 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.
The layout goes in controller.kv
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
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, usable 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.
More documentation
For a full description of the different components of the
KV
language,
advanced usage and limitations, see the documentation for
lang
« Graphics
Integrating with other Frameworks »
US