Version

Quick search

Table Of Contents

Text

An abstraction of text creation. Depending of the selected backend, the accuracy of text rendering may vary.

Changed in version 1.10.1: LabelBase.find_base_direction() added.

Changed in version 1.5.0: LabelBase.line_height added.

Changed in version 1.0.7: The LabelBase does not generate any texture if the text has a width <= 1.

This is the backend layer for rendering text with different text providers, you should only be using this directly if your needs aren’t fulfilled by the Label.

Usage example:

from kivy.core.text import Label as CoreLabel

...
...
my_label = CoreLabel()
my_label.text = 'hello'
# the label is usually not drawn until needed, so force it to draw.
my_label.refresh()
# Now access the texture of the label and use it wherever and
# however you may please.
hello_texture = my_label.texture

Font Context Manager

A font context is a namespace where multiple fonts are loaded; if a font is missing a glyph needed to render text, it can fall back to a different font in the same context. The font context manager can be used to query and manipulate the state of font contexts when using the Pango text provider (no other provider currently implements it).

New in version 1.11.0.

Warning

This feature requires the Pango text provider.

Font contexts can be created automatically by kivy.uix.label.Label or kivy.uix.textinput.TextInput; if a non-existent context is used in one of these classes, it will be created automatically, or if a font file is specified without a context (this creates an isolated context, without support for fallback).

Usage example:

from kivy.uix.label import Label
from kivy.core.text import FontContextManager as FCM

# Create a font context containing system fonts + one custom TTF
FCM.create('system://myapp')
family = FCM.add_font('/path/to/file.ttf')

# These are now interchangeable ways to refer to the custom font:
lbl1 = Label(font_context='system://myapp', family_name=family)
lbl2 = Label(font_context='system://myapp', font_name='/path/to/file.ttf')

# You could also refer to a system font by family, since this is a
# system:// font context
lbl3 = Label(font_context='system://myapp', family_name='Arial')
class kivy.core.text.LabelBase(text='', font_size=12, font_name=None, bold=False, italic=False, underline=False, strikethrough=False, font_family=None, halign='left', valign='bottom', shorten=False, text_size=None, mipmap=False, color=None, line_height=1.0, strip=False, strip_reflow=True, shorten_from='center', split_str=' ', unicode_errors='replace', font_hinting='normal', font_kerning=True, font_blended=True, outline_width=None, outline_color=None, font_context=None, font_features=None, base_direction=None, font_direction='ltr', font_script_name='Latin', text_language=None, limit_render_to_text_bbox=False, **kwargs)[source]

Bases: builtins.object

Core text label. This is the abstract class used by different backends to render text.

Warning

The core text label can’t be changed at runtime. You must recreate one.

Parameters:
font_size: int, defaults to 12

Font size of the text

font_context: str, defaults to None

Context for the specified font (see kivy.uix.label.Label for details). None will autocreate an isolated context named after the resolved font file.

font_name: str, defaults to DEFAULT_FONT

Font name of the text

font_family: str, defaults to None

Font family name to request for drawing, this can only be used with font_context.

bold: bool, defaults to False

Activate “bold” text style

italic: bool, defaults to False

Activate “italic” text style

text_size: tuple, defaults to (None, None)

Add constraint to render the text (inside a bounding box). If no size is given, the label size will be set to the text size.

padding: int|float or list|tuple, defaults to [0, 0, 0, 0].

Padding of the text in the format [padding_left, padding_top, padding_right, padding_bottom]. padding should be int|float or a list|tuple with 1, 2 or 4 elements.

padding_x: float, defaults to 0.0

Left/right padding

padding_y: float, defaults to 0.0

Top/bottom padding

halign: str, defaults to “left”

Horizontal text alignment inside the bounding box

valign: str, defaults to “bottom”

Vertical text alignment inside the bounding box

shorten: bool, defaults to False

Indicate whether the label should attempt to shorten its textual contents as much as possible if a size is given. Setting this to True without an appropriately set size will lead to unexpected results.

shorten_from: str, defaults to center

The side from which we should shorten the text from, can be left, right, or center. E.g. if left, the ellipsis will appear towards the left side and it will display as much text starting from the right as possible.

split_str: string, defaults to ‘ ‘ (space)

The string to use to split the words by when shortening. If empty, we can split after every character filling up the line as much as possible.

max_lines: int, defaults to 0 (unlimited)

If set, this indicate how maximum line are allowed to render the text. Works only if a limitation on text_size is set.

mipmap: bool, defaults to False

Create a mipmap for the texture

strip: bool, defaults to False

Whether each row of text has its leading and trailing spaces stripped. If halign is justify it is implicitly True.

strip_reflow: bool, defaults to True

Whether text that has been reflowed into a second line should be stripped, even if strip is False. This is only in effect when size_hint_x is not None, because otherwise lines are never split.

unicode_errors: str, defaults to ‘replace’

How to handle unicode decode errors. Can be ‘strict’, ‘replace’ or ‘ignore’.

outline_width: int, defaults to None

Width in pixels for the outline.

outline_color: tuple, defaults to (0, 0, 0)

Color of the outline.

font_features: str, defaults to None

OpenType font features in CSS format (Pango only)

base_direction: str, defaults to None (auto)

Text direction, one of None, ‘ltr’, ‘rtl’, ‘weak_ltr’, or ‘weak_rtl’ (Pango only)

text_language: str, defaults to None (user locale)

RFC-3066 format language tag as a string (Pango only)

limit_render_to_text_bbox: bool, defaults to False. PIL only.

If set to True, this parameter indicates that rendering should be limited to the bounding box of the text, excluding any additional white spaces designated for ascent and descent. By limiting the rendering to the bounding box of the text, it ensures a more precise alignment with surrounding elements when utilizing properties such as valign, y, pos, pos_hint, etc.

New in version 2.3.0: limit_render_to_text_bbox was added to allow to limit text rendering to the text bounding box (PIL only).

Deprecated since version 2.2.0: padding_x and padding_y have been deprecated. Please use padding instead.

Changed in version 2.2.0: padding is now a list and defaults to [0, 0, 0, 0]. padding accepts int|float or a list|tuple with 1, 2 or 4 elements.

Changed in version 1.10.1: font_context, font_family, font_features, base_direction and text_language were added.

Changed in version 1.10.0: outline_width and outline_color were added.

Changed in version 1.9.0: strip, strip_reflow, shorten_from, split_str, and unicode_errors were added.

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

Changed in version 1.8.0: max_lines parameters has been added.

Changed in version 1.0.8: size have been deprecated and replaced with text_size.

Changed in version 1.0.7: The valign is now respected. This wasn’t the case previously so you might have an issue in your application if you have not considered this.

property content_height

Return the content height; i.e. the height of the text without any padding.

property content_size

Return the content size (width, height)

property content_width

Return the content width; i.e. the width of the text without any padding.

static find_base_direction(text)[source]

Searches a string the first character that has a strong direction, according to the Unicode bidirectional algorithm. Returns None if the base direction cannot be determined, or one of ‘ltr’ or ‘rtl’.

Note

This feature requires the Pango text provider.

property fontid

Return a unique id for all font parameters

get_cached_extents()[source]

Returns a cached version of the get_extents() function.

>>> func = self._get_cached_extents()
>>> func
<built-in method size of PROVIDER.font.Font object at 0x01E45650>
>>> func('a line')
(36, 18)

Warning

This method returns a size measuring function that is valid for the font settings used at the time get_cached_extents() was called. Any change in the font settings will render the returned function incorrect. You should only use this if you know what you’re doing.

New in version 1.9.0.

get_extents(text)[source]

Return a tuple (width, height) indicating the size of the specified text

static get_system_fonts_dir()[source]

Return the directories used by the system for fonts.

property label

Get/Set the text

refresh()[source]

Force re-rendering of the text

static register(name, fn_regular, fn_italic=None, fn_bold=None, fn_bolditalic=None)[source]

Register an alias for a Font.

New in version 1.1.0.

If you’re using a ttf directly, you might not be able to use the bold/italic properties of the ttf version. If the font is delivered in multiple files (one regular, one italic and one bold), then you need to register these files and use the alias instead.

All the fn_regular/fn_italic/fn_bold parameters are resolved with kivy.resources.resource_find(). If fn_italic/fn_bold are None, fn_regular will be used instead.

render(real=False)[source]

Return a tuple (width, height) to create the image with the user constraints. (width, height) includes the padding.

shorten(text, margin=2)[source]

Shortens the text to fit into a single line by the width specified by text_size [0]. If text_size [0] is None, it returns text unchanged.

split_str and shorten_from determines how the text is shortened.

Params:

text str, the text to be shortened. margin int, the amount of space to leave between the margins and the text. This is in addition to padding_x.

Returns:

the text shortened to fit into a single line.

property text

Get/Set the text

property text_size

Get/set the (width, height) of the ‘ ‘contrained rendering box

property usersize

(deprecated) Use text_size instead.

« Spelling Text layout »