Kv Compiler Contexts and Rules

Describes the classes that captures a kv binding rule as well as the context that stores the rules.

Typical usage:

class MyWidget(Widget):

    kv_ctx = None

    def __init__(self, **kwargs):
        super(MyWidget, self).__init__(**kwargs)
        self.apply_kv()

    @kv()
    def apply_rule(self):
        with KvContext() as self.kv_ctx:
            self.width @= self.height + 10

            with KvRule(name='my_rule') as rule:
                print('callback args is:', rule.largs)
                self.x @= self.y + 25

Then:

>>> widget = MyWidget()
>>> widget.height = 43  # sets widget.width to 53
>>> rule = widget.kv_ctx.named_rules['my_rule']
>>> rule.unbind_rule()  # unbinds the rule
>>> widget.kv_ctx.unbind_all_rules()  # unbinds all the rules

class kivy.lang.compiler.kv_context.KvRule(*binds, delay=None, name=None, triggered_only=False)

Bases: builtins.object

Describes a kv rule.

Parameters:

• *binds –

  captures all positional arguments and add them to the bind list. E.g.:

  with KvRule():
      self.x @= self.y
  

  does the same things as:

  with KvRule(self.y):
      self.x = self.y
  

  and you can add as many positional args there as you like, and the rule will bind to all fo them. The args can be actual variable names, e.g. self.y, or as a string, e.g. “self.y” - they will do the same thing.

• delay –

  the rule type: can be None (default), “canvas”, or a number. Describes the rule type. * If None, it’s a normal kv rule * If “canvas”, it’s meant to be used with a canvas instruction and

  the rule will be scheduled to be executed with other graphics after the frame, rather than every time it is called.

  • If a number, a Clock trigger event will be created with the given delay and when the rule dispatches, the event will be triggered, rather than be executed immediately.
• name – a optional name for the rule. Defaults to None

Class attributes:

Variables:

• largs – The largs provided when the rule is dispatched.
• bind_store – (internal): Maintains a reference to the list that stores all the bindings created for the rule.
• bind_store_leaf_indices – (internal): The list of all the indices in bind_store that store the leaf bindings created for the rule.
• callback – (internal): The callback function that is called by the rule whenever it is dispatched.
• _callback – (internal): If it’s a clock or canvas rule, contains the underlying callback that actually executed the rule. In that case, callback contains the clock trigger or function that schedules the canvas update.

unbind_rule()

Unbinds the rule, so that it will not be triggered by any of the properties that the rule is bound to.

If the rule is already scheduled, e.g. with a canvas instruction or clock trigger, it may still execute (this may change in the future to immediately cancel that as well), but it won’t be scheduled again.

class kivy.lang.compiler.kv_context.KvContext(reinit_after=False)

Bases: builtins.object

Manages kv rules created under the context.

Parameters:reinit_after –

Whether all the rules that are not KvRule.triggered_only should be executed again after the bindings are complete when the KvContext exits. Defaults to False.

This is only useful when bind_on_enter in kv() is False, because then the rules are executed before the bindings occur, and it may be desirable for the rules to be executed again, once all the bindings occurs.

This is particularly useful for circular rules. It is False by default for performance reasons.

Class attributes:

Variables:

• rules –

  List of KvRule Contains all the kv rules created under the context, ignoring rules created under a second context within this context. E.g.:

  with KvContext() as my_ctx:
      self.x @= self.y
      with KvContext() as my_ctx2:
          self.y @= self.height + 10
      with KvRule(name='my_rule'):
          self.width @= self.height
  

  then my_ctx will contain 2 rules, and my_ctx2 will contain 1 rule. The rules are ordered and numbered in the order they occur in the function.

• named_rules – dictionary with all the rules that are named. Similarly to rules, but contains the rules that have been given names. In the example above, my_ctx.named_rules contains one rule with name/key value “my_rule”.
• bind_store – (internal): Maintains a reference to the list that stores all the bindings created for all the rules in the context.
• rebind_functions – (internal): Maintains a reference to all the callbacks used in all the context’s rules.

add_rule(rule)

Adds the rule to the context.

It is called automatically by the compiler and should only be called when manually compiling kv.

unbind_all_rules()

Calls KvRule.unbind_rule() for all the rules in the context to unbind all the rules.

class kivy.lang.compiler.kv_context.KvParserRule(*binds, delay=None, name=None, triggered_only=False)

Bases: kivy.lang.compiler.kv_context.KvRule

Created by the parser when it encounters a KvRule.

It is also used when manually compiling kv.

class kivy.lang.compiler.kv_context.KvParserContext(reinit_after=False)

Bases: kivy.lang.compiler.kv_context.KvContext

Created by the parser when it encounters a KvContext.

It is also used when manually compiling kv.