Quick search

Label(翻訳済み)

_images/label.png

:class:`Label`は文字列を描画するwidgetで、asciiとunicodeの文字列に対応しています。

# hello world text
l = Label(text='Hello world')

# unicode text; can only display glyphs that are available in the font
l = Label(text=u'Hello world ' + unichr(2764))

# multiline text
l = Label(text='Multi\nLine')

# size
l = Label(text='Hello world', font_size='20sp')

文字列とLabelの大きさとの関係

 既定では、Labelの大きさは text に影響されず、textもLabelの大きさには影響されません。もし文字列の描かれる範囲を制限したいなら:attr:~Label.text_size`を指定しないといけません。またLabelを文字列の大きさに合わせて伸縮させたいなら:attr:`~Label.size:をattr:`~Label.texture_size`で縛って下さい。

例えば次のコードでは、Labelの大きさは文字列の大きさ(:attr:`~Label.padding`も含む)と同じになります。

Label:
    size: self.texture_size

又次のコードでは、Labelの文字列は指定された幅(6cm)で折り返され、指定された高さ(4cm)で切り抜かれます。

Label:
    text_size: cm(6), cm(4)

注釈

shortenmax_lines 属性で文字列が溢れる時の振る舞いを制御できます。

上記の属性を組み合わせて、文字列の量に合わせて縦には伸びるが横には伸びず、逆に自身の幅で文字列を折り返しさせるLabelを作るには以下のようになります。

Label:
    text_size: root.width, None
    size: self.texture_size

文字列の位置揃えと折り返し

Label は文字列の位置揃えを制御する為の属性として halignvalign を持っています。でも既定では、文字列の描画されたTexture(texture)はその文字列が入るだけの最小限の大きさしか持たず、 それがLabelの中央に配置されるようになっています。その状態ではvalignは何の効果も持たず、halignは文字列が複数行である時のみ効果があります。一行の文字列では例えhalignをleftに設定していたとしても中央揃えになります。

halignとvalignが意味を成す為には、 文字列の領域の大きさを定める text_size 属性を設定する必要があります。例えば以下のコードではtext_sizeをsizeで縛っています。 こうする事で文字列がLabelの領域内で位置揃え出来るようになるのです。さらにですがこのLabelは自動で自身の幅で文字列が折り返すようにもなっています。

Label:
    text_size: self.size
    halign: 'right'
    valign: 'middle'

Markup text

バージョン 1.1.0 で追加.

Text Markup を使う事で文字列の見た目を変えられます。構文はbbcodeと似ていますが、対応しているのはinline形式のみです。

# hello world with world in bold
l = Label(text='Hello [b]World[/b]', markup=True)

# hello in red, world in blue
l = Label(text='[color=ff3333]Hello[/color][color=3333ff]World[/color]',
    markup = True)

もし文字列がMarkup Textの制御文字として認識されるのを防ぎたければ kivy.utils.escape_markup():: を使って下さい。

text = 'This is an important message [1]'
l = Label(text='[b]' + escape_markup(text) + '[/b]', markup=True)

以下のTagが使えます。

[b][/b]

太字

[i][/i]

イタリック体

[u][/u]

下線

[s][/s]

打ち消し線

[font=<str>][/font]

フォント指定

[size=<integer>][/size]

フォントの大きさを指定

[color=#<color>][/color]

文字列の色を変える

[ref=<str>][/ref]

文字列中にインタラクティブな領域を作る。このTagで囲った文字列の領域は Label.refs で参照できる。

[anchor=<str>]

文字列中にインタラクティブな領域を作る。このTagで囲った部分は Label.anchors で参照できる。

[sub][/sub]

このTagで囲った文字列はその前にある文字列の右下に小さく配置される

[sup][/sup]

このTagで囲った文字列はその前にある文字列の右上に小さく配置される

もし MarkupTextの制御文字である “[” や “]” や “&” をそのまま表示させたければ。それらをエスケープする必要があります。そうする為の簡単な方法を用意しました。

[   -> &bl;
]   -> &br;
&   -> &amp;

これで以下のように書けます。

"[size=24]Hello &bl;World&bt;[/size]"

文字列中のインタラクティブな領域

バージョン 1.1.0 で追加.

Tag``[ref=xxx][/ref]``を使うことで文字列内の任意の部分に、ユーザーの入力に反応する領域を作ることができます。

次の例では単語”World”を[ref][/ref]で囲っています。この単語がクリックされた時には、print_it関数が仮引数valueに’world’が渡された状態で呼ばれるようになってます。

def print_it(instance, value):
    print('User clicked on', value)
widget = Label(text='Hello [ref=world]World[/ref]', markup=True)
widget.bind(on_ref_press=print_it)

見た目を良くしたいなら色を付けることも出来ます。上の例の “text=” を以下に書き換えて下さい。

'Hello [ref=world][color=0000ff]World[/color][/ref]'

色んな言語への対応

Kivyが初期状態で使っているフォントは世界中全ての言語の文字を含んでいるわけではありません。そしてフォントに含まれていない文字があれば、その文字は豆腐として描画されます。

もしそのような文字を表示したければ、それらの文字を含むフォントをKvで以下のように設定してあげましょう。

<Label>:
    font_name: '/<path>/<to>/<font>'

あなたの作ったWidgetsが読み込まれる前に、上のコードが読み込まれる必要があることに注意しましょう。

使用例

次の例ではLabel中のanchor([a][/a]で囲った部分])とreferences([ref][/ref]で囲った部分)に色で印をつけています。

from kivy.app import App
from kivy.uix.label import Label
from kivy.clock import Clock
from kivy.graphics import Color, Rectangle


class TestApp(App):

    @staticmethod
    def get_x(label, ref_x):
        """ Return the x value of the ref/anchor relative to the canvas """
        return label.center_x - label.texture_size[0] * 0.5 + ref_x

    @staticmethod
    def get_y(label, ref_y):
        """ Return the y value of the ref/anchor relative to the canvas """
        # Note the inversion of direction, as y values start at the top of
        # the texture and increase downwards
        return label.center_y + label.texture_size[1] * 0.5 - ref_y

    def show_marks(self, label):

        # Indicate the position of the anchors with a red top marker
        for name, anc in label.anchors.items():
            with label.canvas:
                Color(1, 0, 0)
                Rectangle(pos=(self.get_x(label, anc[0]),
                               self.get_y(label, anc[1])),
                          size=(3, 3))

        # Draw a green surround around the refs. Note the sizes y inversion
        for name, boxes in label.refs.items():
            for box in boxes:
                with label.canvas:
                    Color(0, 1, 0, 0.25)
                    Rectangle(pos=(self.get_x(label, box[0]),
                                   self.get_y(label, box[1])),
                              size=(box[2] - box[0],
                                    box[1] - box[3]))

    def build(self):
        label = Label(
            text='[anchor=a]a\nChars [anchor=b]b\n[ref=myref]ref[/ref]',
            markup=True)
        Clock.schedule_once(lambda dt: self.show_marks(label), 1)
        return label

TestApp().run()
class kivy.uix.label.Label(**kwargs)[ソース]

ベースクラス: kivy.uix.widget.Widget

詳しくはmoduleのdocumentationを見て下さい

Events:
on_ref_press

ユーザーが”[ref][/ref]”で囲まれた文字列をClickした時に呼ばれる

anchors

バージョン 1.1.0 で追加.

文字列の中の全ての ``[anchor=xxx]` で囲った部分を指す辞書。辞書のKeyが”xxx”で値が位置になっていて、位置は文字列の左上からの相対座標になっています。(下がyの正方向)。又anchorの名前(xxxの部分)はかぶらないようにすべきです。複数あったとしても最初の物しか記録されません。

anchorは以下のように使います。

text = """
    [anchor=title1][size=24]This is my Big title.[/size]
    [anchor=content]Hello world
"""

そして文字列が描画された後にこのanchors属性から位置を得られます。

>>> widget = Label(text=text, markup=True)
>>> widget.texture_update()
>>> widget.anchors
{"content": (20, 32), "title1": (20, 16)}

注釈

この属性は markup がTrueである時のみ使えます。

bold

太字を使うか否か

注釈

Fontによってはこの属性は全く描画に影響を与えません。

boldBooleanProperty 型で既定値はFalse.

color

文字列の色。(r, g, b, a)形式で設定する。

colorListProperty 型で既定値は [1, 1, 1, 1].

disabled_color

Labelが無効な状態の時の文字列の色。 (r, g, b, a) 形式。

バージョン 1.8.0 で追加.

disabled_colorListProperty 型で既定値は [1, 1, 1, .3]。

disabled_outline_color

Labelが無効な状態の時の文字列の縁取りの色。 (r, g, b)形式。

注釈

この機能を使うにはSDL2のtext providerが必要です。

バージョン 1.10.0 で追加.

disabled_outline_colorListProperty で既定値は [0, 0, 0]

ellipsis_options

文字列の省略表記(‘...’)に使う書式

辞書形式で設定値を受け付けます。 markup が True で 省略表記された文字列(‘...’)にのみ適用されます。 Label に使える全てのFontに関する設定値がこの :attr:`ellipsis_options`に使え、ここで指定されていない場合は周りの文字列の設定値を使います。

Label:
    text: 'Some very long line which will be cut'
    markup: True
    shorten: True
    ellipsis_options: {'color':(1,0.5,0.5,1),'underline':True}

バージョン 2.0.0 で追加.

ellipsis_optionsDictProperty 型で既定値は {} (空の辞書).

font_blended

文字列の描画を blendedとsolid どちらで行うか(アンチエイリアスを行うか否か)

注釈

この機能を使うにはSDL2のtext providerが必要です。

バージョン 1.10.0 で追加.

font_blendedBooleanProperty 型で既定値は True

font_hinting

文字列の描画に使う’hinting’オプション。値は`’normal’, `’light’, ‘mono’, None のいずれか。(訳者注釈: このオプションの意味が全く分からない為、訳せませんでした。)

注釈

この機能を使うにはSDL2のtext providerが必要です。

バージョン 1.10.0 で追加.

font_hintingOptionProperty 型で既定値は ‘normal’

font_kerning

kerning(文字間の隙間の調節)を行うか否か

注釈

この機能を使うにはSDL2のtext providerが必要です。

バージョン 1.10.0 で追加.

font_kerningBooleanProperty 型で既定値は True.

font_name

使いたいFontのファイル名。相対パスと絶対パスどちらも可で、相対パスの場合は resource_find() 関数を使って検索されます。

警告

text providerによってはFontファイルは無視されます。でもほとんどの場合は問題にはなりません。

もしあなたの使っている言語/文字がFontに含まれていない場合、本来の文字に代えて豆腐’[]’が表示されます。これを直すにはそれを含むFontを使うしかありません。例えば unicodechar を表示したいのなら freesans.ttf を使って下さい。

font_nameStringProperty 型で既定値は ‘Roboto’. そしてこの値は Config で得たものです。

font_size

Fontの大きさ。pixel単位。

font_sizeNumericProperty 型で既定値は 15sp.

halign

横の位置揃え

halignOptionProperty 型で既定値は ‘left’。 使える値は left, center, right , justify。

警告

この属性は文字列が描画されたTextureの位置を変えるのではなく、Texture内での文字列の描画する位置を変えます。(Texture自体の位置はLabelの中央)。この属性を使う際には:attr:`text_size`も設定する事になるでしょう。

バージョン 1.6.0 で変更: halign に設定可能な値として justify が追加されました。

is_shortened

この属性は shorten が True の時、描画された文字列に省略表記(‘...’)を使わずに済んだのか否かを表している。

バージョン 1.10.0 で追加.

is_shortenedBooleanProperty 型で既定値は False.

italic

イタリック体のFontを使うか否か

注釈

Fontに依ってはitalic属性は効果を持たないかもしれない

italicBooleanProperty 型で既定値は False.

line_height

行の高さ。例えば line_height = 2とすると行同士の間隔が二倍になる。

line_heightNumericProperty で既定値は 1.0.

バージョン 1.5.0 で追加.

markup

バージョン 1.1.0 で追加.

もし True なら, 文字列の描画には class:~kivy.core.text.markup.MarkupLabel: が使われる。そうすると文字列の書式をTagを使って変える事が出来るようになる。詳しくは Text Markup を見て下さい。

markupBooleanProperty 型で既定値は False.

max_lines

行の最大数。既定値は0でその場合は無制限になる。 shorten がTrueの時はこの属性は無視される事に注意して下さい。(省略表記が有効な時は文字列は常に一行に収まります。)

バージョン 1.8.0 で追加.

max_linesNumericProperty 型で既定値は 0.

mipmap

OpenGL の Mipmapping を使うか否か。詳しくは Mipmapping を読んで下さい。

バージョン 1.0.7 で追加.

mipmapBooleanProperty 型で既定値はFalse.

outline_color

文字列を縁取りする時の色。(r, g, b)形式。

注釈

この機能を使うにはSDL2のtext providerが必要です。

バージョン 1.10.0 で追加.

outline_colorListProperty 型で既定値は [0, 0, 0].

outline_width

文字列を縁取りする時の線の幅。Noneを設定すると縁取りが行われなくなる。

注釈

この機能を使うにはSDL2のtext providerが必要です。

バージョン 1.10.0 で追加.

outline_widthNumericProperty で既定値はNone.

padding

Texture内に描画する文字列に設ける余白。(padding_x, padding_y)の形式で指定。

paddingReferenceListProperty 型で、(padding_x, padding_y) と繋がっている。

padding_x

左右に設ける余白

padding_xNumericProperty 型で既定値は0.

バージョン 1.9.0 で変更: padding_x は期待通りに動くよう修正済みです。以前は負の値を渡す必要がありました。

padding_y

上下に設ける余白

padding_yNumericProperty 型で既定値は 0.

バージョン 1.9.0 で変更: padding_y は期待通りに動くよう修正済みです。以前は負の値を渡す必要がありました。

refs

バージョン 1.1.0 で追加.

文字列中の[ref=xxx][/ref]で囲った部分の描画された位置をこの属性を通して得られる。

例えば次のように書くと

Check out my [ref=hello]link[/ref]

refs属性は次のようになる。

{'hello': ((64, 0, 78, 16), )}

[ref=hello][/ref]で囲った部分の文字列を包括する長方形の座標が(x1, y1, x2, y2)の形で入っています。これらの座標は文字列のTextureの左上からの相対位置で、yの正方向が下になっています。名前(helloの部分)がかぶった[ref]が複数あっても構いません。その場合はtupleに追加されていくだけです。

現在のLabelの実装では[ref][/ref]で囲まれた文字列があると自動で当たり判定を行い、その部分をClickしたときに on_ref_press を呼び出すようになっています。

あなたは次のようにしてbindできます。

def print_it(instance, value):
    print('User click on', value)
widget = Label(text='Hello [ref=world]World[/ref]', markup=True)
widget.on_ref_press(print_it)

注釈

この属性は markup がTrueである時のみ使えます。

shorten

文字列の省略表記(‘...’)を行うか否かを決めます。適切な text_size を設定せずにこの属性を True にすると、予期しない結果になります。

shorten_fromsplit_str を使う事で、 text のどの位置からどのように省略表記に置き換えるかを制御できます。

shortenBooleanProperty 型で既定値は False.

shorten_from

文字列のどの部分を省略するか。 left, right, center から選べます。

例えば left に設定した場合、省略表記のドット(‘...’)は左側に現れ、右側の内容が省略されずに残ります。またこの属性は text_size [0] が None以外でないと意味を持ちません。text_size [0] で示された幅に合うように文字列を縮めるからです。

バージョン 1.9.0 で追加.

shorten_fromOptionProperty 型で既定値は center.

split_str

text を省略する過程で行う文字列の分割に使う区切り文字

例えば:attr:`split_str`が空白一字(‘ ‘)で:attr:`text`が英語のような空白で単語を区切る言語だった場合は単語毎に分割される事になり、結果 単語の途中で省略されることが無くなります。もし:attr:`split_str`が空文字列なら:attr:`text`は一文字毎に分割され、結果 単語が途中で切れてしまう事があります。

バージョン 1.9.0 で追加.

split_strStringProperty 型で既定値は ‘’ (空文字列).

strikethrough

文字列に打ち消し線を入れる

注釈

この機能を使うにはSDL2のtext providerが必要です。

バージョン 1.10.0 で追加.

strikethroughBooleanProperty 型で既定値は False.

strip

各行の先頭と末尾にある空白と改行を取り除くか否か。Trueなら取り除かれ、:attr:`halign`次第ですが各行は右端または左端にきっちり寄せられます。 又:attr:`halign`がjustifyの時は、:attr:`strip`は暗黙的にTrueになります。

バージョン 1.9.0 で追加.

stripBooleanProperty 型で既定値はFalse。

text

Labelの文字列。

簡単な Hello World プログラムの作成

widget = Label(text='Hello world')

もしunicode文字列でLabelを作りたければ

widget = Label(text=u'My unicode string')

textStringProperty 型で既定値は ‘’。

text_size

既定ではLabelの文字列の領域には何の制約もかかっていません。でもこの属性を設定する事でそれができます。文字列はこの値で指定された矩形に収まるように配置され、収まり切らなかった部分は捨てられます。

値がNoneでない時、それがそのまま:attr:`texture_size`になります。

バージョン 1.0.4 で追加.

例えばLabelの大きさに関わらず文字列の領域を、幅を200に高さを制限無しにしたいなら

Label(text='Very big big line', text_size=(200, None))

注釈

このtext_size属性は:class:~kivy.core.text.Label classにある:attr:`~kivy.core.text.Label.usersize`属性と同じです。 (Constructorの引数では’usersize’ではなく’size’)

text_sizeListProperty 型で既定値は (None, None)です。 この場合は文字列の領域に何の制約もかかりません。

texture

文字列が描かれたTexture。Labelの属性が変われば描画は自動で行われる。このTextureを何か別の描画処理に利用する事もできる。

Textureの作り方に依り、この属性には Texture 又は TextureRegion が入っている。

警告

texture の更新は次のフレームの描画時に行われるようになっています。もし今すぐに更新したければ:attr:texture`にアクセスする前に:meth:`texture_update methodを呼んでください。

l = Label(text='Hello world')
# l.texture is good
l.font_size = '50sp'
# l.texture is not updated yet
l.texture_update()
# l.texture is good now.

textureObjectProperty 型で既定値は None.

texture_size

texture`の大きさ。もし:attr:`text_size が [None, None]だと、textureは文字列の描画に必要なだけ大きくなる。そうでなければ:attr:`text_size`と同じ大きさになる。

:attr:`text_size`が[None, None]の時、Textureは文字列が入るだけの最小限の大きさを保とうとします。

警告

:attr:`texture_size`は:attr:`texture`の後に設定されます。 もしあなたが:attr:`texture`に関数をbindしていた場合、その関数が呼び出された時に :attr:`texture_size`はまだ更新されていません。なので代わりに :attr:`texture_size`をbindして下さい。

texture_update(*largs)[ソース]

現在のLabelの属性の設定値でその場でTextureを作り直す。

この関数を呼んだ後、texturetexture_size が順に更新される。

underline

文字列に下線を引く。

注釈

この機能を使うにはSDL2のtext providerが必要です。

バージョン 1.10.0 で追加.

underlineBooleanProperty 型で既定値はFalse。

unicode_errors

Unicodeのdecodeに失敗した時の振る舞い。’strict’, ‘replace’. ‘ignore’のいずれか。

バージョン 1.9.0 で追加.

unicode_errorsOptionProperty 型で既定値は`’replace’`

valign

縦の位置揃え。

valignOptionProperty 型で既定値は`bottom’。次の値を使うことが出来る。‘bottom’, ‘middle’, ‘center’`(’middle’と同じ), `’top’

バージョン 1.10.0 で変更: ‘center’`が‘middle’`の別名として加わりました。

警告

この属性は文字列が描画されたTextureの位置を変えるのではなく、Texture内での文字列の描画する位置を変えます。(Texture自体の位置はLabelの中央)。この属性を使う際には:attr:`text_size`も設定する事になるでしょう。