Python Kivyの使い方（参考）～APIリファレンスのKivy Languageを翻訳してみた～

2017/06/20 更新

公式マニュアルの翻訳に載りました。以降修正などは以下のリンクで行います。修正先はkivyの最新バージョンである1.10に対応しております

• 公式マニュアルの翻訳先

KivyのAPIリファレンスのKivy Language の翻訳です。Programming Guide(翻訳済み) » Kv language(翻訳済みには記載がない説明があるので翻訳してみました。

Kivy Language

 Module: kivy.langAdded in 1.0.0

Kivy Languageは、ユーザーインターフェイスとインタラクションを記述するための専用の言語です。この言語をQtのQML（http://qt.nokia.com ） と比較することもできますが、Rule定義（CSSとよく似ています）、テンプレートなどの新しい概念が含まれています。

バージョン1.7.0で変更：ビルダーはリアルタイムでキャンバス表現を実行しません。最初に実行する必要があるすべての式をパックし、入力をディスパッチした後、フレームを描画する直前に実行します。キャンバス描画を強制的に実行したい場合は、Builder.syncを呼び出します。.

kv lang用の実験的プロファイリングツールも含まれています。環境変数KIVY_PROFILE_LANG = 1を設定することによって、それをアクティブにすることができます。その後、builder_stats.htmlという名前のhtmlファイルが生成されます。

概要（Overview）

Kivy Languageは、使用可能ないくつかの構成で構成されています。

Rule
RuleはCSSのルールに似ています。Ruleは、widgetツリーの特定のwidget（またはそのクラス）に適用されて特定の方法で変更されます。Ruleを使用して対話的な動作を指定したり、Ruleを使用して、適用するwidgetのグラフィカルな表現を追加できます。 cls属性（例：cls = MyTestWidget）を使用すると、widgetの特定のクラスをターゲティングできます（クラスのCSSコンセプトに似ています）。

Root Widget
Kivy Languageを使用して、ユーザーインターフェイス全体を作成できます。 kvファイルには、最大で1つのroot widgetが含まれる必要があります。

Dynamic Classes
（バージョン1.7.0で導入されました）Dynamic Classを使用すると、Pythonファイル側で宣言なしで新しいwidgetとRuleをすぐに作成できます。

Templates (deprecated)
（バージョン1.0.5で導入され、バージョン1.7.0で廃止されました）Templateは、リストのコンテンツのスタイリング（たとえば、左のアイコン、右のテキスト）など、アプリケーションの一部を埋めるために使用されました。Dynamic Classによって非推奨になりました。

kvファイルの構文(Syntax of a kv File)

Kivy Languageファイルのファイル拡張子は.kvです。

ファイルの内容は常にKivyヘッダーで始める必要があります。バージョンは使用しているKivy Languageのバージョンに置き換える必要があります。1.0の場合：

#:kivy `1.0`

# content here

コンテンツには、Rule定義、Root Widget、Dynamic Classの定義、およびTemplateを含めることができます。

# Syntax of a rule definition. Note that several Rules can share the same
# definition (as in CSS). Note the braces: they are part of the definition.
<Rule1,Rule2>:
    # .. definitions ..

<Rule3>:
    # .. definitions ..

# Syntax for creating a root widget
RootClassName:
    # .. definitions ..

# Syntax for creating a dynamic class
<NewWidget@BaseClass>:
    # .. definitions ..

# Syntax for create a template
[TemplateName@BaseClass1,BaseClass2]:
    # .. definitions ..

Rule、Root Widget、Dynamic Class、または定義しているTemplateのどれかにかかわらず、定義は次のようになります。

# With the braces it's a rule. Without them, it's a root widget.
<ClassName>:
    prop1: value1
    prop2: value2

    canvas:
        CanvasInstruction1:
            canvasprop1: value1
        CanvasInstruction2:
            canvasprop2: value2

    AnotherClass:
        prop3: value1

ここでprop1とprop2はClassNameのプロパティであり、prop3はAnotherClassのプロパティです。widgetに指定された名前のプロパティがない場合、ObjectPropertyが自動的に作成されてwidgetに追加されます。

AnotherClassが作成されされ、ClassNameインスタンスの子として追加されます。

• インデントは重要で、一貫してなければなりません。スペースは、最初にインデントされた行に使用されるスペースの倍数でなければなりません。タブとスペースをミックスすることはお勧めしません。
• プロパティの値は1行に与えなければなりません（少なくとも今のところ）。
• キャンバスのプロパティは特別です。グラフィックスの指示を入れて、現在のクラスをグラフィカルに表現できます。

以下に、root widgetを含むkvファイルの簡単な例を示します

#:kivy 1.0

Button:
    text: 'Hello world'

バージョン1.7.0で変更されました：インデントはスペース4つに制限されていません。スペースは、最初にインデントされた行に使用されるスペースの倍数でなければなりません。

load_file（）メソッドとload_string（）メソッドはどちらも、kvファイル/文字列で定義されたルートwidgetを返します。また、後で使用するために、クラスとテンプレート定義をFactoryに追加します。

式の値、on_property、idsおよび予約済みキーワード(Value Expressions, on_property Expressions, ids and Reserved Keywords)

プロパティの値を指定すると、その値はPythonの式として評価されます。この式は静的でも動的でもかまいません。つまり予約されたキーワードを使用して他のプロパティの値を使用できます。

self
キーワードselfは "現在のwidgetのインスタンス"を参照します：

Button:
    text: 'My state is %s' % self.state

root
このキーワードは、Rule定義でのみ使用でき、Ruleのroot widget（Ruleの最初のインスタンス）を表します。

<MyWidget>:
    custom: 'Hello world'
    Button:
        text: root.custom

app
このキーワードは、常にあなたのアプリインスタンスを参照します。 Pythonのkivy.app.App.get_running_app（）の呼び出しと同じです。

Label:
    text: app.name

args

このキーワードはon_<action>コールバックで使用できます。これは、コールバックに渡される引数を参照します。

TextInput:
    on_focus: self.insert_text("Focus" if args[1] else "No focus")

ids

クラス定義には、キーワードとして使用できるIDを含められます。

<MyWidget>:
    Button:
        id: btn1
    Button:
        text: 'The state of the other button is %s' % btn1.state

このidはwidgetのインスタンスでは使用できないことに注意してください。外部参照専用に使用されています。 idはwidget自体のwidgetではなく、widgetの弱い参照です。widget自体はid .__ self_（この場合はbtn1 ._ self__）でアクセスできます。

kvファイルが処理されると、idでタグ付けされたすべてのwidgetへの弱い参照がroot widgetsのids辞書に追加されます。言い換えれば、上の例に続いて、ボタンのステータスに次のようにアクセスできます：

widget = MyWidget()
state = widget.ids["btn1"].state

# Or, as an alternative syntax,
state = widget.ids.btn1.state

一番外側のwidgetは、他のRuleが適用される前に、すべての内部widgetにkvRuleを適用することに注意してください。つまり、内部widgetにidsが含まれている場合、これらのidsは内部widgetのinit関数では使用できない可能性があります。

有効な表現(Valid expressons)

kvファイルにはpythonステートメントを受け入れる場所が2つあります。プロパティの後に、式の結果（下記のようなボタンのテキストなど）とon_propertyの後にプロパティが更新されます（on_stateなど）。

前者の場合、式は1行にしかできず、改行をエスケープして複数行に拡張することはできず、値を返す必要があります。有効な式の例は、text：self.stateと（self.state == 'normal' else 'down'の場合は 'up'）です。

後者の場合、インデントレベルを追加しない限り、改行をエスケープする複数行のステートメントを含む複数の単一行ステートメントが有効です。

有効なステートメントの例は次のとおりです。

on_press: if self.state == 'normal': print('normal')
on_state:
    if self.state == 'normal': print('normal')
    else: print('down')
    if self.state == 'normal': \
    print('multiline normal')
    for i in range(10): print(i)
    print([1,2,3,4,
    5,6,7])

無効なステートメントの例：

on_state:
    if self.state == 'normal':
        print('normal')

値とプロパティの関係(Relation Between Values and Properties)

Kivy Languageを使用すると、裏で自動的に作業が行われることがわかります。 PropertiesはObserver Design Patternを実装していることを知っておくべきです。つまり、プロパティの値が変更されたときに呼び出されるように独自の関数をバインドできます（つまり、潜在的な変更についてプロパティを受動的に観察します）。

Kivy Languageは、値式のプロパティを検出し、変更が発生したときに式を介してプロパティを自動的に更新するための作成コールバックを作成します。

この動作を示す簡単な例を次に示します。

Button:
    text: str(self.state)

この例では、パーサーはself.stateが動的な値（プロパティ）であることを検出します。ボタンのstate プロパティは、いつでも（ユーザーが触れると）変更できます。このボタンでは、状態が変化しても、テキストとして独自の状態を表示する必要があります。これを行うために、Buttonのstateプロパティを使用してボタンのtextプロパティの値に使用します。これはボタンに表示されるテキストを制御します（状態も文字列表現に変換します）。ボタンの状態が変わるたびに、テキストプロパティが自動的に更新されます。

覚えておいてください。値はPython式です！つまり、次のような面白いことができます。

Button:
    text: 'Plop world' if self.state == 'normal' else 'Release me!'

Buttonのtextは、Buttonの状態とともに変わります。デフォルトでは、Buttonのtextは「Plop world」になりますが、Buttonを押すと、テキストは「Release me！」に変わります。

より正確には、Kivy Languageパーサは、Xがselfまたはrootまたはappまたは既知のidであり、aおよびbがプロパティであるXab形式のすべての部分文字列を検出します。次に、適切な依存関係を追加して変更します。たとえば、これは期待どおりに動作します。

<IndexedExample>:
    beta: self.a.b[self.c.d]

しかし、今後期待されるパーサの制限により、以下のようなことはできません：

<BadExample>:
    beta: self.a.b[self.c.d].e.f

確かに.e.f部分は期待されたパターンに従わず、適切な依存関係が設定されないため認識されません。代わりに、次の制約を許容するために中間プロパティを導入する必要があります。

<GoodExample>:
    alpha: self.a.b[self.c.d]
    beta: self.alpha.e.f

グラフィカルな指示(Graphical Instructions)

グラフィカルな指示は、Kivy言語の特別な部分です。それらは 'canvas'プロパティ定義によって処理されます：

Widget:
    canvas:
        Color:
            rgb: (1, 1, 1)
        Rectangle:
            size: self.size
            pos: self.pos

canvasプロパティ内に追加されたすべてのクラスは、Instructionクラスから派生する必要があります。 canvasプロパティの中にWidgetクラスを置くことはできません（widgetはグラフィックス関係の命令ではないので意味をなしません）。

テーマを利用したいのであれば、CSSと同じ質問が出ます：どのRuleが最初に実行されたのですか？この場合、Ruleは処理順（トップダウン）で実行されます。

ボタンのレンダリング方法を変更したい場合は、独自のkvファイルを作成し、次のように追加することができます：

<Button>:
    canvas:
        Color:
            rgb: (1, 0, 0)
        Rectangle:
            pos: self.pos
            size: self.size
        Rectangle:
            pos: self.pos
            size: self.texture_size
            texture: self.texture

これにより、上記のすべてのRuleに加えて、左下にラベルが付いた赤い背景のボタンが表示されます。Clearコマンドを使用すると、前の手順をすべてクリアできます。

<Button>:
    canvas:
        Clear
        Color:
            rgb: (1, 0, 0)
        Rectangle:
            pos: self.pos
            size: self.size
        Rectangle:
            pos: self.pos
            size: self.texture_size
            texture: self.texture

Clearコマンドに続くRuleだけが考慮されます

Dynamic classes

Dynamic classを使用すると、最初にPython宣言を使わずに、新しいwidgetトをすぐに作成できます。Dynamic classの構文は、Ruleと似ていますが、サブクラス化する基本クラスを指定する必要があります。

構文は次のようになります。

# Simple inheritance
<NewWidget@Button>:
    # kv code here ...

# Multiple inheritance
<NewWidget@ButtonBehavior+Label>:
    # kv code here ...

@文字は、クラス名をサブクラス化するクラスと区別するために使用されます。 Pythonではいかに相当します。

# Simple inheritance
class NewWidget(Button):
    pass

# Multiple inheritance
class NewWidget(ButtonBehavior, Label):
    pass

新しいプロパティは、通常はPythonコードで追加され、最初に宣言する必要があります。プロパティがDynamic classに存在しない場合は、ObjectProperty（1.8.0より前）または適切な型付きプロパティ（1.8.0から）として自動的に作成されます。

バージョン1.8.0で変更されました：プロパティ値がすぐに評価できる式（外部バインディングなし）であれば、その値はプロパティのデフォルト値として使用され、値の型はPropertyクラスの特殊化。言い換えれば、hello： "world"を宣言すると、新しいStringPropertyがデフォルト値 "world"でインスタンス化されます。リスト、タプル、辞書、文字列がサポートされています。

基本的な画像ボタンを実装して、これらの動的クラスの使い方を説明しましょう。 Buttonからクラスを派生させ、画像ファイル名のプロパティを追加しているだけです。

<ImageButton@Button>:
    source: None

    Image:
        source: root.source
        pos: root.pos
        size: root.size

# let's use the new classes in another rule:
<MainUI>:
    BoxLayout:
        ImageButton:
            source: 'hello.png'
            on_press: root.do_something()
        ImageButton:
            source: 'world.png'
            on_press: root.do_something_else()

Pythonでは、次のように動的クラスのインスタンスを作成できます。

from kivy.factory import Factory
button_inst = Factory.ImageButton()

Note

Dynamic classを使用すると、子クラスはその親クラスの前に宣言できます。しかし、これは、親プロパティ/メソッドが子のプロパティ/メソッドをオーバーライドする直感的ではない状況につながります。この動作を選択した場合は注意してください。

Templates

バージョン1.7.0で変更されました：テンプレートの使用は推奨されなくなりました。Dynamic classを代わりに使用してください。

　テンプレートの構文（Syntax of templates）

KivyでTemplateを使用するには、2つのことが必要です。

1. コンテキストのために渡すコンテキスト（Template内のctxになります）。
2. Templateのkv定義。

Templateの構文は以下の通りです。

# With only one base class
[ClassName@BaseClass]:
    # .. definitions ..

# With more than one base class
[ClassName@BaseClass1,BaseClass2]:
    # .. definitions ..

たとえば、リストの場合は、左にイメージ、右にラベルを持つエントリを作成する必要があります。その定義を使いやすくするためのテンプレートを作成できます。したがって、コンテキスト内に2つのエントリを使用するテンプレートを作成します。画像ファイル名とタイトルの場合は以下の通りです。

　[IconItem@BoxLayout]:
    Image:
        source: ctx.image
    Label:
        text: ctx.title

Pythonでは、次のようにテンプレートをインスタンス化できます。

from kivy.lang import Builder

# create a template with hello world + an image
# the context values should be passed as kwargs to the Builder.template
# function
icon1 = Builder.template('IconItem', title='Hello world',
    image='myimage.png')

# create a second template with other information
ctx = {'title': 'Another hello world',
       'image': 'myimage2.png'}
icon2 = Builder.template('IconItem', **ctx)
# and use icon1 and icon2 as other widget.

Templateの例(Template example)

ほとんどの場合、kv langで画面を作成する場合には、多くの再定義を使用します。この例では、BoxLayoutに基づいてツールバーを作成し、on_touch_downイベントに反応するいくつかのImage widgetを配置します。

<MyToolbar>:
    BoxLayout:
        Image:
            source: 'data/text.png'
            size: self.texture_size
            size_hint: None, None
            on_touch_down: self.collide_point(*args[1].pos) and root.create_text()

        Image:
            source: 'data/image.png'
            size: self.texture_size
            size_hint: None, None
            on_touch_down: self.collide_point(*args[1].pos) and root.create_image()

        Image:
            source: 'data/video.png'
            size: self.texture_size
            size_hint: None, None
            on_touch_down: self.collide_point(*args[1].pos) and root.create_video()

sizeとsize_hint属性はまったく同じであることがわかります。それ以上に、on_touch_downのコールバックと画像が変化しています。これらはTemplateの可変部分で、コンテキストに入れられます。 ImageのTemplateを作成してみましょう：

[ToolbarButton@Image]:

    # This is the same as before
    size: self.texture_size
    size_hint: None, None

    # Now, we are using the ctx for the variable part of the template
    source: 'data/%s.png' % ctx.image
    on_touch_down: self.collide_point(*args[1].pos) and ctx.callback()

Templateは、MyToolbarRuleで直接使用できます。

<MyToolbar>:
    BoxLayout:
        ToolbarButton:
            image: 'text'
            callback: root.create_text
        ToolbarButton:
            image: 'image'
            callback: root.create_image
        ToolbarButton:
            image: 'video'
            callback: root.create_video

これで全て完了です。

Templateの制限(Template limitations)

コンテキストを作成するときは、次のようにします。

• "root"以外の参照は使用できません。

<MyRule>:
    Widget:
        id: mywidget
        value: 'bleh'
    Template:
        ctxkey: mywidget.value # << fail, this references the id
        # mywidget

• 動的部分のすべてが理解されるわけではありません。

<MyRule>:
    Template:
        ctxkey: 'value 1' if root.prop1 else 'value2' # << even if
        # root.prop1 is a property, if it changes value, ctxkey
        # will not be updated

Templateの定義は、同様に名前が付けられた定義全体を置き換えるため、継承をサポートしません。

widgetスタイルの再定義( Redefining a widget’s style)

Pythonのプロパティを.kv定義のスタイルを使わずに使用するために、widgetから継承したいことがあります。たとえば、Labelから継承したいのですが、Labelから継承したキャンバス命令を自動的に使用するのではなく、独自のキャンバス命令を定義することもできます。これは、.kvスタイル定義のクラス名の前にダッシュ（ - ）を付けることで実現できます。

myapp.pyでは:

class MyWidget(Label):
    pass

次に、my.kvでは:

<-MyWidget>:
    canvas:
        Color:
            rgb: 1, 1, 1
        Rectangle:
            size: (32, 32)

MyWidgetは、Labelから継承された命令を使用せずにキャンバス内にColorおよびRectangle命令を持つようになりました。

widgetのプロパティスタイルを再定義する(Redefining a widget’s property style)

スタイルを再定義するのと同様に、特定のプロパティに適用されたスタイルを除いて、KV定義のスタイルをすべて保持したままwidgetから継承したいことがあります。たとえば、Buttonから継承したいのですが、background_normalとbackground_downの値に頼るのではなく、独自のstate_imageを設定することもできます。これは、.kvスタイル定義のstate_imageプロパティ名の前にダッシュ（ - ）を付けることで実現できます。

myapp.pyでは

class MyWidget(Button):

    new_background = StringProperty('my_background.png')

そしてmy.kvでは

<MyWidget>:
    -state_image: self.new_background

MyWidgetはnew_backgroundだけで設定されたstate_imageバックグラウンドを持つようになり、以前のスタイルではstate_imageが設定されていない可能性があります。

Note

以前のRuleはクリアされていますが、widgetの作成中に適用され、ダッシュ付きの新しいRuleに達すると削除されます。これは、最初は以前のRuleを使用してプロパティを設定できることを意味します。

kwargsとKVRuleの適用順序(Order of kwargs and KV rule application)

プロパティは、KVとPythonで初期化できます。例えば、KVでは

<MyRule@Widget>:
    text: 'Hello'
    ramp: 45.
    order: self.x + 10

MyRule（）は、3つのkivyプロパティをすべて指定のKV値に初期化します。 Pythonとは別に、kivyプロパティとしてプロパティが既に存在する場合、MyRule（line = 'Bye'、side = 55）などのプロパティを使用できます。

しかし、MyRule（text = 'Bye'、order = 55）が実行されたときのプロパティの最終値はどうなりますか？クイックRuleは、Pythonの初期化はKVの初期化よりも一定の規則に対して強いということです。

具体的には、python初期化子に与えられたkwargが常に最初に適用されます。上の例では、テキストは「Bye」に設定され、orderは「55」に設定されています。そして、Python初期化子提供値を上書きする定数規則を除いて、すべてのKV規則が適用されます。

つまり、テキストのようなバインディングを作成しないKVRuleは text:'Hello'とramp：45です。そのプロパティの値がPythonで提供されている場合、そのRuleは適用されません。

したがって、MyRule（text = 'Bye'、order = 55）の例では、テキストは「Bye」、ランプは45となり、バインディングを作成するorderは55に設定されますが、KVRuleself.x + 10が何であっても適用されます。

バージョン1.9.1で変更されました。以前は、KVRuleは常にPython値を上書きしていましたが、Python値は定数Ruleで上書きされません。

言語のディレクティブ(Lang Directives)

ディレクティブを使用すると、インポートや定数定義などの宣言的なコマンドをlangファイルに追加できます。ディレクティブは、次の形式でコメントとして追加されます。

#:<directivename> <options>

import

1.0.5.で追加されました

書き方:

#:import <alias> <package>

記載することpackageをimportできます。

#:import os os

<Rule>:
    Button:
        text: os.getcwd()

より複雑な書き方は、

#:import ut kivy.utils

<Rule>:
    canvas:
        Color:
            rgba: ut.get_random_color()

1.0.7.で追加されました

モジュールから直接クラスをインポートできます。

#: import Animation kivy.animation.Animation
<Rule>:
    on_prop: Animation(x=.5).start(self)

set

1.0.6.で追加されました

書き方

#:set <key> <expr>

kv内の任意の場所で使用できるキーを設定します。例えば以下の通りです。

#:set my_color (.4, .3, .4)
#:set my_color_hl (.5, .4, .5)

<Rule>:
    state: 'normal'
    canvas:
        Color:
            rgb: my_color if self.state == 'normal' else my_color_hl

include

1.0.5で追加されました

文法:

#:include [force] <file>

外部Kivyファイルが含まれます。これにより、複雑なwidgetをそれぞれのファイルに分割できます。インクルードが強制されると、ファイルは最初にアンロードされてから再度ロードされます。例えば以下のようになります。

# Test.kv
#:include mycomponent.kv
#:include force mybutton.kv

<Rule>:
    state: 'normal'
    MyButton:
    MyComponent:

# mycomponent.kv
#:include mybutton.kv

<MyComponent>:
    MyButton:

# mybutton.kv

<MyButton>:
    canvas:
        Color:
            rgb: (1.0, 0.0, 0.0)
        Rectangle:
            pos: self.pos
            size: (self.size[0]/4, self.size[1]/4)

API

class kivy.lang.Observable

Added in 1.9.0

Bases: kivy.event.ObjectWithUid

Observableは、バインディングに必要なメソッドを定義するスタブクラスです。 EventDispatcherは、バインディングインタフェースを実装するクラスの1例です。詳細については、EventDispatcherを参照してください。

fbind()

Added in 1.9.0

EventDispatcher.fbind()をみてください。

Note

Observableから継承した可能性のある派生クラスとの下位互換性を維持するために、fbind（）メソッドが追加されました。 fbind（）のデフォルト実装は、uidとlargs / kwargsを保存しながらバインドするために渡す部分関数を作成することです。しかし、funbind（）（そしてunbind_uid（））は、まず、largs / kwargsまたはuidを使ってこの部分関数を検索してから、返された関数に対してunbind（）を呼び出さなければならないので、かなり非効率です。より良いパフォーマンスを得るために直接バインドするには、これらのメソッドを派生クラスで上書きすることをお勧めします。
EventDispatcher.fbind（）と同様に、このメソッドは失敗した場合は0を返し、成功した場合は肯定的な一意のuidを返します。このuidは、unbind_uid（）で使用できます。
```

funbind()

Added in 1.9.0

fbind() と EventDispatcher.funbind()を見てください

unbind_uid()

Added in 1.9.0

fbind() と EventDispatcher.unbind_uid()をみてください。

class kivy.lang.BuilderBase

Added in 1.0.0

Bases: builtins.object

ビルダーは、kvファイルを解析し、結果を内部ルール、テンプレートなどにマージするためのParserを作成します。

既定では、ビルダーはwidgetで使用されるグローバルなKivyインスタンスで、既定のものに加えて他のkvファイルを読み込めます。

apply(widget, ignored_consts=set())

Added in 1.0.0

ウィジェットと一致するすべてのルールを検索して適用します。

ignored_constsは、そのウィジェットの定数KVルール（つまりバインディングを作成しないルール）が適用されないプロパティ名であるセットまたはリストタイプです。これにより、例えば、 Pythonで初期化された値を上書きする定数ルールをスキップします

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

Added in 1.9.2

rule_nameウィジェットと一致するすべてのルールを検索し、widgetに適用します。

ignored_constsは、そのウィジェットの定数KVルール（つまりバインディングを作成しないルール）が適用されないプロパティ名であるセットまたはリストタイプです。これにより、例えば、 Pythonで初期化された値を上書きする定数ルールをスキップします

load_file(filename, **kwargs)

Added in 1.0.0

言語ビルダーにファイルを挿入し、kvファイルのroot widget（定義されている場合）を返します。

パラメーター：
rulesonly：bool型、デフォルトはFalseです。
Trueの場合、定義内にroot widgetがある場合、Builderは例外を発生させます。

** load_string(string, **kwargs)

Added in 1.0.0

Language Builderに文字列を挿入し、kv文字列のroot widget（定義されている場合）を返します。

パラメーター：
rulesonly：bool型、デフォルトはFalseです。
Trueの場合、定義内にルートウィジェットがある場合、Builderは例外を発生させます。

** match(widget) Added in 1.0.0

Added in 1.0.0

widgetに一致するParserRuleオブジェクトのリストを返します。

** match_rule_name(rule_name)

Added in 1.0.0

widgetに一致するParserRuleオブジェクトのリストを返します。

** sync()

Added in 1.7.0

canvasに関連するすべての式の実行など、すべての待機操作を実行します。

** template(*args, **ctx)

Added in 1.0.5

特定のコンテキストを使用して特殊なTemplate を作成します。

Template を使用すると、kv lang定義からカスタムwidgetを作成することができます。Template の使用状況を確認してください。

unbind_property(widget, name)

Added in 1.9.1

名前を設定するwidgetのすべてのルールによって作成されたハンドラーをアンバインドします。

これは、フォームを取るwidgetのすべてのルールを効果的にクリアします

name: rule

例:

>>> 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]

** unbind_widget(uid)

Added in 1.7.2

WidgetのKVルールによって作成されたすべてのハンドラをアンバインドします。 BuilderがWidgetのデストラクタでそれを使用しているので、kivy.uix.widget.Widget.uidはWidget自体の代わりにここで渡されます。

これにより、このWidgetに関連するすべてのKVルールが効果的に消去されます。
例は以下の通りです。:

>>> 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]

unload_file(filename)

以前にインポートされたファイルに関連付けられているすべてのruleをアンロードします。

Added in 1.0.8

Warning

これにより、現在のwidgetですでに適用または使用されているruleまたはtemplates は削除されません。次のウィジェットの作成またはtemplates 呼び出しにのみ影響します。

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

Added in 1.0.0

Bases: kivy.lang.parser.ParserException

Builderがwidgetにruleを適用できなかったときに発生するエクセプション。

class kivy.lang.Parser(**kwargs)

Added in 1.0.0

Bases: builtins.object

Kivy LanguageファイルまたはKivyコンテンツを解析するParserオブジェクトを作成します。

parse(content)

Added in 1.0.0

Parserファイルの内容を解析し、root objectのリストを返します。

parse_level(level, lines, spaces=0)

Added in 1.0.0

現在のレベル（レベル*スペース）の字下げを解析します。

strip_comments(lines)

Added in 1.0.0

すべての行のコメントを一括削除します。コメントは、行の終わりではなく、単一の行に記述する必要があります。コメント行の最初の非空白文字は＃でなければなりません。

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

Added in 1.0.0

Bases: Exception

kvファイルで何らかの不具合が発生した場合に発生するエクセプション。