Table Of Contents
Label¶
The Label widget is for rendering text. It supports ascii and unicode strings:
# 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')
Markup text¶
New in version 1.1.0.
You can change the style of the text using Text Markup. The syntax is near the bbcode syntax, but only the inline styling is allowed:
# 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)
If you need to escape the markup from the current text, use kivy.utils.escape_markup():
text = 'This is an important message [1]'
l = Label(text='[b]' + escape_markup(text) + '[/b]', markup=True)
The following tags are available:
- [b][/b]
- Activate bold text
- [i][/i]
- Activate italic text
- [font=<str>][/font]
- Change the font
- [size=<integer>][/size]
- Change the font size
- [color=#<color>][/color]
- Change the text color
- [ref=<str>][/ref]
- Add an interactive zone. The reference + bounding box inside the reference will be available in Label.refs
- [anchor=<str>]
- Put an anchor in the text. You can get the position of your anchor within the text with Label.anchors
- [sub][/sub]
- Display the text at a subscript position relative to the text before it.
- [sup][/sup]
- Display the text at a superscript position relative to the text before it.
If you want to render the markup text with a character [ or ] or &, you need to escape them. We created a simple syntax:
[ -> &bl;
] -> &br;
& -> &
Then you can write:
"[size=24]Hello &bl;World&bt;[/size]"
Interactive Zone in Text¶
New in version 1.1.0.
You can now have definable “links” using text markup. The idea is to be able to detect when the user clicks on part of the text, and to react. The tag [ref=xxx] is used for that.
In this example, we are creating a reference on the word “World”. When a click happens on it, the function print_it will be called with the name of the reference:
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)
For a better rendering, you could add a color for the reference. Replace the text= in the previous example with:
'Hello [ref=world][color=0000ff]World[/color][/ref]'
- class kivy.uix.label.Label(**kwargs)¶
Bases: kivy.uix.widget.Widget
Label class, see module documentation for more information.
Events : - on_ref_press
Fired when the user clicks on a word referenced with a [ref] tag in a text markup.
- anchors¶
New in version 1.1.0.
Position of all the [anchor=xxx] markup put into the text.
You can put anchors in your markup text:
text = """ [anchor=title1][size=24]This is my Big title.[/size] [anchor=content]Hello world """
Then, all the [anchor=] references will be removed, and you’ll get all the anchor positions in this property (only after rendering):
>>> widget = Label(text=text, markup=True) >>> widget.texture_update() >>> widget.anchors {"content": (20, 32), "title1": (20, 16)}
Note
This is working only with markup text. You need markup set to True.
- bold¶
Indicates use of the bold version of your font.
Note
Depending of your font, the bold attribute may have no impact on your text rendering.
bold is a BooleanProperty, default to False
- color¶
Text color, in the format (r, g, b, a)
color is a ListProperty, default to [1, 1, 1, 1].
- font_name¶
Filename of the font to use. The path can be absolute or relative. Relative paths are resolved by the resource_find() function.
Warning
Depending of your text provider, the font file can be ignored. However, you can mostly use this without trouble.
If the font used lacks the glyphs for the particular language/symbols you are using, you will see ‘[]’ blank box characters instead of the actual glyphs. The solution is to use a font that has the glyphs you need to display. For example, to display
, use a font such as freesans.ttf that has the glyph.
font_name is a StringProperty, default to ‘DroidSans’.
- font_size¶
Font size of the text, in pixels.
font_size is a NumericProperty, default to 12dp.
- halign¶
Horizontal alignment of the text.
halign is a OptionProperty, default to ‘left’. Available options are : left, center and right.
Warning
This doesn’t change the position of the text texture of the Label (centered), only the position of the text in this texture. You probably want to bind the size of the Label to the texture_size or set a text_size.
Changed in version 1.6.0.
- italic¶
Indicates use of the italic version of your font.
Note
Depending of your font, the italic attribute may have no impact on your text rendering.
italic is a BooleanProperty, default to False
- line_height¶
Line Height for the text. e.g. line_height = 2 will cause the spacing between lines to be twice the size.
line_height is a NumericProperty, default to 1.0.
New in version 1.5.0.
- markup¶
New in version 1.1.0.
If true, the text will be rendered with MarkupLabel: you can change the style of the text using tags. Check Text Markup documentation for more information.
markup is a BooleanProperty, default to False.
- mipmap¶
Indicates OpenGL mipmapping applied to texture or not. Read Mipmapping for more information.
New in version 1.0.7.
mipmap is a BooleanProperty, default to False.
- padding¶
Padding of the text in the format (padding_x, padding_y)
padding is a ReferenceListProperty of (padding_x, padding_y) properties.
- padding_x¶
Horizontal padding of the text inside the widget box.
padding_x is a NumericProperty, default to 0
- padding_y¶
Vertical padding of the text inside the widget box.
padding_x is a NumericProperty, default to 0
- refs¶
New in version 1.1.0.
List of [ref=xxx] markup put into the text, with the bounding box of all the words contained in a ref, only after rendering.
For example, if you wrote:
Check out my [ref=hello]link[/hello]
The refs will be set with:
{'hello': ((64, 0, 78, 16), )}
You know that the reference “hello” have a bounding box set at (x1, y1, x2, y2). The current Label implementation uses these references if they exist in your markup text, automatically doing the collision with the touch, and dispatching an on_ref_press event.
You can bind a ref event like this:
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)
Note
This is working only with markup text. You need markup set to True.
- shorten¶
Indicates whether the label should attempt to shorten its textual contents as much as possible if a text_size is given. Setting this to True without an appropriately set text_size will lead to unexpected results.
shorten is a BooleanProperty, default to False.
- text¶
Text of the label.
Creation of a simple hello world:
widget = Label(text='Hello world')
If you want to create the widget with an unicode string, use:
widget = Label(text=u'My unicode string')
- text_size¶
By default, the label is not constrained to any bounding box. You can set the size constraint of the label with this property.
New in version 1.0.4.
For example, whatever your current widget size is, if you want the label to be created in a box with width=200 and unlimited height:
Label(text='Very big big line', text_size=(200, None))
Note
This text_size property is the same as usersize property in Label class. (It is named size= in constructor.)
text_size is a ListProperty, default to (None, None), meaning no size restriction by default.
- texture¶
Texture object of the text. The text is rendered automatically when a property changes. The OpenGL texture created in this operation is stored in this property. You can use this texture for any graphics elements.
Depending on the texture creation, the value will be a Texture or TextureRegion object.
Warning
The texture update is scheduled for the next frame. If you need the texture immediately after changing a property, you have to call the texture_update() method before accessing texture:
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 is a ObjectProperty, default to None.
- texture_size¶
Texture size of the text.
Warning
The texture_size is set after the texture property. If you listen for changes to texture, texture_size will not be up-to-date in your callback. Bind to texture_size instead.
- texture_update(*largs)¶
Force texture recreation with the current Label properties.
After this function call, the texture and texture_size will be updated in this order.
- valign¶
Vertical alignment of the text.
valign is a OptionProperty, default to ‘bottom’. Available options are : bottom, middle and top.
Warning
This doesn’t change the position of the text texture of the Label (centered), only the position of the text in this texture. You probably want to bind the size of the Label to the texture_size or set a text_size.