Table Of Contents

• Builder

Builder

Class used for the registering and application of rules for specific widgets.

class kivy.lang.builder.Observable

Bases: kivy.event.ObjectWithUid

Observable is a stub class defining the methods required for binding. EventDispatcher is (the) one example of a class that implements the binding interface. See EventDispatcher for details.

New in version 1.9.0.

fbind()

See EventDispatcher.fbind().

Note

To keep backward compatibility with derived classes which may have inherited from Observable before, the fbind() method was added. The default implementation of fbind() is to create a partial function that it passes to bind while saving the uid and largs/kwargs. However, funbind() (and unbind_uid()) are fairly inefficient since we have to first lookup this partial function using the largs/kwargs or uid and then call unbind() on the returned function. It is recommended to overwrite these methods in derived classes to bind directly for better performance.

Similarly to EventDispatcher.fbind(), this method returns 0 on failure and a positive unique uid on success. This uid can be used with unbind_uid().

funbind()

See fbind() and EventDispatcher.funbind().

unbind_uid()

See fbind() and EventDispatcher.unbind_uid().

kivy.lang.builder.Builder = <kivy.lang.builder.BuilderBase object>

Main instance of a BuilderBase.

class kivy.lang.builder.BuilderBase

Bases: builtins.object

The Builder is responsible for creating a Parser for parsing a kv file, merging the results into its internal rules, templates, etc.

By default, Builder is a global Kivy instance used in widgets that you can use to load other kv files in addition to the default ones.

apply(widget, ignored_consts=set())

Search all the rules that match the widget and apply them.

ignored_consts is a set or list type whose elements are property names for which constant KV rules (i.e. those that don’t create bindings) of that widget will not be applied. This allows e.g. skipping constant rules that overwrite a value initialized in python.

apply_rules(widget, rule_name, ignored_consts=set())

Search all the rules that match rule_name widget and apply them to widget.

New in version 1.10.0.

ignored_consts is a set or list type whose elements are property names for which constant KV rules (i.e. those that don’t create bindings) of that widget will not be applied. This allows e.g. skipping constant rules that overwrite a value initialized in python.

load_file(filename, **kwargs)

Insert a file into the language builder and return the root widget (if defined) of the kv file.

Parameters:

rulesonly: bool, defaults to False

If True, the Builder will raise an exception if you have a root widget inside the definition.

load_string(string, **kwargs)

Insert a string into the Language Builder and return the root widget (if defined) of the kv string.

Parameters:

rulesonly: bool, defaults to False

If True, the Builder will raise an exception if you have a root widget inside the definition.

filename: str, defaults to None

If specified, the filename used to index the kv rules.

The filename parameter can be used to unload kv strings in the same way as you unload kv files. This can be achieved using pseudo file names e.g.:

Build.load_string("""
    <MyRule>:
        Label:
            text="Hello"
""", filename="myrule.kv")

can be unloaded via:

Build.unload_file("myrule.kv")

match(widget)

Return a list of ParserRule objects matching the widget.

match_rule_name(rule_name)

Return a list of ParserRule objects matching the widget.

sync()

Execute all the waiting operations, such as the execution of all the expressions related to the canvas.

New in version 1.7.0.

template(*args, **ctx)

Create a specialized template using a specific context.

New in version 1.0.5.

With templates, you can construct custom widgets from a kv lang definition by giving them a context. Check Template usage.

unbind_property(widget, name)

Unbind the handlers created by all the rules of the widget that set the name.

This effectively clears all the rules of widget that take the form:

name: rule

For example:

>>> w = Builder.load_string('''
... Widget:
...     height: self.width / 2. if self.disabled else self.width
...     x: self.y + 50
... ''')
>>> w.size
[100, 100]
>>> w.pos
[50, 0]
>>> w.width = 500
>>> w.size
[500, 500]
>>> Builder.unbind_property(w, 'height')
>>> w.width = 222
>>> w.size
[222, 500]
>>> w.y = 500
>>> w.pos
[550, 500]

New in version 1.9.1.

unbind_widget(uid)

Unbind all the handlers created by the KV rules of the widget. The kivy.uix.widget.Widget.uid is passed here instead of the widget itself, because Builder is using it in the widget destructor.

This effectively clears all the KV rules associated with this widget. For example:

>>> w = Builder.load_string('''
... Widget:
...     height: self.width / 2. if self.disabled else self.width
...     x: self.y + 50
... ''')
>>> w.size
[100, 100]
>>> w.pos
[50, 0]
>>> w.width = 500
>>> w.size
[500, 500]
>>> Builder.unbind_widget(w.uid)
>>> w.width = 222
>>> w.y = 500
>>> w.size
[222, 500]
>>> w.pos
[50, 500]

New in version 1.7.2.

unload_file(filename)

Unload all rules associated with a previously imported file.

New in version 1.0.8.

Warning

This will not remove rules or templates already applied/used on current widgets. It will only effect the next widgets creation or template invocation.

exception kivy.lang.builder.BuilderException(context, line, message, cause=None)

Bases: kivy.lang.parser.ParserException

Exception raised when the Builder failed to apply a rule on a widget.

« Kivy Language

Parser »