# 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 similar to 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 [ or ] or & character, you need to escape them. We created a simple syntax:

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

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 this word is clicked, 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 prettier 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]'


## Usage example¶

The following example marks the anchors and references contained in a label:

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)[source]

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 in the text. These co-ordinates are relative to the top left corner of the text, with the y value increasing downwards. Anchors names should be unique and only the first occurence of any duplicate anchors will be recorded.

You can place anchors in your markup text as follows:

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 works 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 and defaults to False.

color

Text color, in the format (r, g, b, a)

color is a ListProperty and defaults to [1, 1, 1, 1].

disabled_color

Text color, in the format (r, g, b, a)

New in version 1.8.0.

disabled_color is a ListProperty and defaults to [1, 1, 1, .5].

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 problems.

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 and defaults to ‘DroidSans’.

font_size

Font size of the text, in pixels.

font_size is a NumericProperty and defaults to 12dp.

halign

Horizontal alignment of the text.

halign is an OptionProperty and defaults to ‘left’. Available options are : left, center, right and justify.

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: A new option was added to halign, namely justify.

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 and defaults 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 and defaults to 1.0.

New in version 1.5.0.

markup

New in version 1.1.0.

If True, the text will be rendered using the MarkupLabel: you can change the style of the text using tags. Check the Text Markup documentation for more information.

markup is a BooleanProperty and defaults to False.

max_lines

Maximum number of lines to use, defaults to 0, which means unlimited. Please note that shorten take over this property. (with shorten, the text is always one line.)

New in version 1.8.0.

max_lines is a NumericProperty and defaults to 0.

mipmap

Indicates whether OpenGL mipmapping is applied to the texture or not. Read Mipmapping for more information.

New in version 1.0.7.

mipmap is a BooleanProperty and defaults to False.

Horizontal padding of the text inside the widget box.

padding_x is a NumericProperty and defaults to 0.

Changed in version 1.9.0: padding_x has been fixed to work as expected. In the past, the text was padded by the negative of its values.

Vertical padding of the text inside the widget box.

padding_y is a NumericProperty and defaults to 0.

Changed in version 1.9.0: padding_y has been fixed to work as expected. In the past, the text was padded by the negative of its values.

refs

New in version 1.1.0.

List of [ref=xxx] markup items in the text with the bounding box of all the words contained in a ref, available only after rendering.

For example, if you wrote:

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

The refs will be set with:

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


The references marked “hello” have a bounding box at (x1, y1, x2, y2). These co-ordinates are relative to the top left corner of the text, with the y value increasing downwards. You can define multiple refs with the same name: each occurence will be added as another (x1, y1, x2, y2) tuple to this list.

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 works 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_from and split_str control the direction from which the text is split, as well as where in the text we are allowed to split.

shorten is a BooleanProperty and defaults to False.

shorten_from

The side from which we should shorten the text from, can be left, right, or center.

For example, if left, the ellipsis will appear towards the left side and we will display as much text starting from the right as possible. Similar to shorten, this option only applies when text_size [0] is not None, In this case, the string is shortened to fit within the specified width.

New in version 1.9.0.

shorten_from is a OptionProperty and defaults to center.

split_str

The string used to split the text while shortening the string when shorten is True.

For example, if it’s a space, the string will be broken into words and as many whole words that can fit into a single line will be displayed. If shorten_from is the empty string, ‘’, we split on every character fitting as much text as possible into the line.

New in version 1.9.0.

split_str is a StringProperty and defaults to ‘’ (the empty string).

strip

Whether leading and trailing spaces and newlines should be stripped from each displayed line. If True, every line will start at the right or left edge, depending on halign. If halign is justify it is implicitly True.

New in version 1.9.0.

strip is a BooleanProperty and defaults 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 is a StringProperty and defaults to ‘’.

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. The text will autoflow into the constrains. So although the font size will not be reduced, the text will be arranged to fit into the box as best as possible, with any text still outside the box clipped.

This sets and clips texture_size to text_size if not None.

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 the usersize property in the Label class. (It is named size= in the constructor.)

text_size is a ListProperty and defaults 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 an ObjectProperty and defaults to None.

texture_size

Texture size of the text. The size is determined by the font size and text. If text_size is [None, None], the texture will be the size required to fit the text, otherwise it’s clipped to fit text_size.

When text_size is [None, None], one can bind to texture_size and rescale it proportionally to fit the size of the label in order to make the text fit maximally in the label.

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)[source]

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 an OptionProperty and defaults 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 within this texture. You probably want to bind the size of the Label to the texture_size or set a text_size to change this behavior.