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={}, rule_children=None, dispatch_kv_post=False)

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

Parameters

widget: Widget

The widget whose class rules should be applied to this widget.

ignored_consts: set

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.

rule_children: list

If not None, it should be a list that will be populated with all the widgets created by the kv rules being applied.

Changed in version 1.11.0.

dispatch_kv_post: bool

Normally the class Widget dispatches the on_kv_post event to widgets created during kv rule application. But if the rules are manually applied by calling apply(), that may not happen, so if this is True, we will dispatch the on_kv_post event where needed after applying the rules to widget (we won’t dispatch it for widget itself).

Defaults to False.

Changed in version 1.11.0.

apply_rules(widget, rule_name, ignored_consts={}, rule_children=None, dispatch_kv_post=False)

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

New in version 1.10.0.

Parameters

widget: Widget

The widget to whom the matching rules should be applied to.

ignored_consts: set

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.

rule_children: list

If not None, it should be a list that will be populated with all the widgets created by the kv rules being applied.

Changed in version 1.11.0.

dispatch_kv_post: bool

Normally the class Widget dispatches the on_kv_post event to widgets created during kv rule application. But if the rules are manually applied by calling apply(), that may not happen, so if this is True, we will dispatch the on_kv_post event where needed after applying the rules to widget (we won’t dispatch it for widget itself).

Defaults to False.

Changed in version 1.11.0.

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 »