Table Of Contents
Label(翻訳済み)¶
: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)
上記の属性を組み合わせて、文字列の量に合わせて縦には伸びるが横には伸びず、逆に自身の幅で文字列を折り返しさせるLabelを作るには以下のようになります。
Label:
text_size: root.width, None
size: self.texture_size
文字列の位置揃えと折り返し¶
Label は文字列の位置揃えを制御する為の属性として halign と valign を持っています。でも既定では、文字列の描画された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;
& -> &
これで以下のように書けます。
"[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によってはこの属性は全く描画に影響を与えません。
boldはBooleanProperty型で既定値はFalse.
-
color¶ 文字列の色。(r, g, b, a)形式で設定する。
colorはListProperty型で既定値は [1, 1, 1, 1].
-
disabled_color¶ Labelが無効な状態の時の文字列の色。 (r, g, b, a) 形式。
バージョン 1.8.0 で追加.
disabled_colorはListProperty型で既定値は [1, 1, 1, .3]。
-
disabled_outline_color¶ Labelが無効な状態の時の文字列の縁取りの色。 (r, g, b)形式。
注釈
この機能を使うにはSDL2のtext providerが必要です。
バージョン 1.10.0 で追加.
disabled_outline_colorはListPropertyで既定値は [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_optionsはDictProperty型で既定値は {} (空の辞書).
-
font_blended¶ 文字列の描画を blendedとsolid どちらで行うか(アンチエイリアスを行うか否か)
注釈
この機能を使うにはSDL2のtext providerが必要です。
バージョン 1.10.0 で追加.
font_blendedはBooleanProperty型で既定値は True
-
font_hinting¶ 文字列の描画に使う’hinting’オプション。値は`’normal’, `’light’, ‘mono’, None のいずれか。(訳者注釈: このオプションの意味が全く分からない為、訳せませんでした。)
注釈
この機能を使うにはSDL2のtext providerが必要です。
バージョン 1.10.0 で追加.
font_hintingはOptionProperty型で既定値は ‘normal’
-
font_kerning¶ kerning(文字間の隙間の調節)を行うか否か
注釈
この機能を使うにはSDL2のtext providerが必要です。
バージョン 1.10.0 で追加.
font_kerningはBooleanProperty型で既定値は True.
-
font_name¶ 使いたいFontのファイル名。相対パスと絶対パスどちらも可で、相対パスの場合は
resource_find()関数を使って検索されます。警告
text providerによってはFontファイルは無視されます。でもほとんどの場合は問題にはなりません。
もしあなたの使っている言語/文字がFontに含まれていない場合、本来の文字に代えて豆腐’[]’が表示されます。これを直すにはそれを含むFontを使うしかありません。例えば
を表示したいのなら freesans.ttf を使って下さい。font_nameはStringProperty型で既定値は ‘Roboto’. そしてこの値はConfigで得たものです。
-
font_size¶ Fontの大きさ。pixel単位。
font_sizeはNumericProperty型で既定値は 15sp.
-
halign¶ 横の位置揃え
halignはOptionProperty型で既定値は ‘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_shortenedはBooleanProperty型で既定値は False.
-
italic¶ イタリック体のFontを使うか否か
注釈
Fontに依ってはitalic属性は効果を持たないかもしれない
italicはBooleanProperty型で既定値は False.
-
line_height¶ 行の高さ。例えば line_height = 2とすると行同士の間隔が二倍になる。
line_heightはNumericPropertyで既定値は 1.0.バージョン 1.5.0 で追加.
-
markup¶ バージョン 1.1.0 で追加.
もし True なら, 文字列の描画には class:~kivy.core.text.markup.MarkupLabel: が使われる。そうすると文字列の書式をTagを使って変える事が出来るようになる。詳しくは Text Markup を見て下さい。
markupはBooleanProperty型で既定値は False.
-
max_lines¶ 行の最大数。既定値は0でその場合は無制限になる。
shortenがTrueの時はこの属性は無視される事に注意して下さい。(省略表記が有効な時は文字列は常に一行に収まります。)バージョン 1.8.0 で追加.
max_linesはNumericProperty型で既定値は 0.
-
mipmap¶ OpenGL の Mipmapping を使うか否か。詳しくは Mipmapping を読んで下さい。
バージョン 1.0.7 で追加.
mipmapはBooleanProperty型で既定値はFalse.
-
outline_color¶ 文字列を縁取りする時の色。(r, g, b)形式。
注釈
この機能を使うにはSDL2のtext providerが必要です。
バージョン 1.10.0 で追加.
outline_colorはListProperty型で既定値は [0, 0, 0].
-
outline_width¶ 文字列を縁取りする時の線の幅。Noneを設定すると縁取りが行われなくなる。
注釈
この機能を使うにはSDL2のtext providerが必要です。
バージョン 1.10.0 で追加.
outline_widthはNumericPropertyで既定値はNone.
-
padding¶ Texture内に描画する文字列に設ける余白。(padding_x, padding_y)の形式で指定。
paddingはReferenceListProperty型で、(padding_x,padding_y) と繋がっている。
-
padding_x¶ 左右に設ける余白
padding_xはNumericProperty型で既定値は0.バージョン 1.9.0 で変更: padding_x は期待通りに動くよう修正済みです。以前は負の値を渡す必要がありました。
-
padding_y¶ 上下に設ける余白
padding_yはNumericProperty型で既定値は 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_fromとsplit_strを使う事で、textのどの位置からどのように省略表記に置き換えるかを制御できます。shortenはBooleanProperty型で既定値は False.
-
shorten_from¶ 文字列のどの部分を省略するか。 left, right, center から選べます。
例えば left に設定した場合、省略表記のドット(‘...’)は左側に現れ、右側の内容が省略されずに残ります。またこの属性は
text_size[0] が None以外でないと意味を持ちません。text_size[0] で示された幅に合うように文字列を縮めるからです。バージョン 1.9.0 で追加.
shorten_fromはOptionProperty型で既定値は center.
-
split_str¶ textを省略する過程で行う文字列の分割に使う区切り文字例えば:attr:`split_str`が空白一字(‘ ‘)で:attr:`text`が英語のような空白で単語を区切る言語だった場合は単語毎に分割される事になり、結果 単語の途中で省略されることが無くなります。もし:attr:`split_str`が空文字列なら:attr:`text`は一文字毎に分割され、結果 単語が途中で切れてしまう事があります。
バージョン 1.9.0 で追加.
split_strはStringProperty型で既定値は ‘’ (空文字列).
-
strikethrough¶ 文字列に打ち消し線を入れる
注釈
この機能を使うにはSDL2のtext providerが必要です。
バージョン 1.10.0 で追加.
strikethroughはBooleanProperty型で既定値は False.
-
strip¶ 各行の先頭と末尾にある空白と改行を取り除くか否か。Trueなら取り除かれ、:attr:`halign`次第ですが各行は右端または左端にきっちり寄せられます。 又:attr:`halign`がjustifyの時は、:attr:`strip`は暗黙的にTrueになります。
バージョン 1.9.0 で追加.
stripはBooleanProperty型で既定値はFalse。
-
text¶ Labelの文字列。
簡単な Hello World プログラムの作成
widget = Label(text='Hello world')
もしunicode文字列でLabelを作りたければ
widget = Label(text=u'My unicode string')
textはStringProperty型で既定値は ‘’。
-
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_sizeはListProperty型で既定値は (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.
textureはObjectProperty型で既定値は None.
-
texture_size¶ texture`の大きさ。もし:attr:`text_sizeが [None, None]だと、textureは文字列の描画に必要なだけ大きくなる。そうでなければ:attr:`text_size`と同じ大きさになる。:attr:`text_size`が[None, None]の時、Textureは文字列が入るだけの最小限の大きさを保とうとします。
-
texture_update(*largs)[ソース]¶ 現在のLabelの属性の設定値でその場でTextureを作り直す。
この関数を呼んだ後、
textureとtexture_sizeが順に更新される。
-
underline¶ 文字列に下線を引く。
注釈
この機能を使うにはSDL2のtext providerが必要です。
バージョン 1.10.0 で追加.
underlineはBooleanProperty型で既定値はFalse。
-
unicode_errors¶ Unicodeのdecodeに失敗した時の振る舞い。’strict’, ‘replace’. ‘ignore’のいずれか。
バージョン 1.9.0 で追加.
unicode_errorsはOptionProperty型で既定値は`’replace’`。
-
valign¶ 縦の位置揃え。
valignはOptionProperty型で既定値は`bottom’。次の値を使うことが出来る。‘bottom’, ‘middle’, ‘center’`(’middle’と同じ), `’top’。バージョン 1.10.0 で変更: ‘center’`が‘middle’`の別名として加わりました。
警告
この属性は文字列が描画されたTextureの位置を変えるのではなく、Texture内での文字列の描画する位置を変えます。(Texture自体の位置はLabelの中央)。この属性を使う際には:attr:`text_size`も設定する事になるでしょう。