Tooltip❖

Module path❖
kivydk.uix.tooltip

Overview❖

Implements the default tooltip widget used by KiviDK. This widget provides a ready‑to‑use tooltip suitable for general applications, allowing developers to benefit from tooltip functionality without creating a custom widget.

The widget conforms to TooltipTemplate and is fully compatible with TooltipManager. Developers may use it directly or substitute their own tooltip widget when custom styling or interaction is required.

Reference❖

class Tooltip(**kwargs)❖

Bases: TooltipTemplate

Default tooltip widget implementation.

Designed to serve as a general‑purpose tooltip for most applications, this widget integrates with TooltipManager and can be replaced with a custom implementation when needed.

padding: VariableListProperty❖

Padding between the widget’s bounding box and its content.

The padding may be specified as one , two or four values. These are expanded into a list of four values: [left, top, right, bottom].

Default value❖
[6, 4, 6, 4]
background_color: ColorProperty❖

Tint color applied to the background_texture.

Default value❖
[1.0, 1.0, 1.0, 1.0]
background_texture: StringProperty❖

Background image applied to the entire widget.

Default value❖
"atlas://data/images/defaulttheme/textinput"
background_border: VariableListProperty❖

Border definition used when rendering background_texture. This controls how the texture is sliced, allowing custom backgrounds to be applied.

The background_border may be specified as one , two or four values. These are expanded into a list of four values: [left, top, right, bottom].

Default value❖
[4, 4, 4, 4]
foreground_color: ColorProperty❖

Color used to render the tooltip text, in RGBA format.

Default value❖
[0.0, 0.0, 0.0, 1.0]
font_context: StringProperty❖

Font context used to render the tooltip text.

Technical details

The font context determines how font files are grouped and resolved. When set to None, the font is used in isolation, guaranteeing that rendering uses the TTF file specified by font_name. When a context name is provided, the font file is loaded into that context, enabling fallback between all fonts registered within it.

When a font context is active, rendering is not guaranteed to use the specified TTF file for every glyph. Pango may substitute glyphs from other fonts in the same context if it considers them a better match.

If Kivy is linked against a system-wide installation of FontConfig, you can load system fonts by using a context name that begins with the special prefix system://. This loads the system fontconfig configuration and then adds your application-specific fonts on top of it. Be aware that this increases the risk of family-name collisions and Pango may choose a system font instead of your custom font file.

Note

This feature requires the Pango text provider.

Default value❖
None
font_family: StringProperty❖

Font family used to render the tooltip text.

Technical details

This option is only relevant when using the font_context setting. The specified font family will be requested from the active font context, but it may not exist or multiple fonts may share the same family name.

The value must be a family name (string) available in the selected font context—for example, a system font in a system:// context, or a custom font registered through kivy.core.text.FontContextManager. If set to None, font selection is determined by the font_name attribute.

Tip

When referencing a custom font file via font_name, this attribute should remain None. The family name is automatically managed in that case.

Note

This feature requires the Pango text provider.

Default value❖
None
font_name: StringProperty❖

Font name or file used to render the tooltip text.

Technical details

The path may be absolute or relative. Relative paths are resolved using resource_find.

Warning

Depending on the active text provider, the specified font file may be ignored. In most cases, however, it works without issues.

If the selected font does not contain the glyphs required for the language or symbols you are displaying, missing characters will appear as blank box placeholders (‘[]’). To avoid this, choose a font that includes the necessary glyphs.

Note

When the default value is None, Kivy falls back to the Roboto font. This default is taken from Config.

Default value❖
None
font_size: NumericProperty❖

Font size used to render the tooltip text.

Default value❖
"16sp"
width_max: NumericProperty❖

Maximum width of the widget.

Default value❖
256
height_max: NumericProperty❖

Maximum height of the widget.

Default value❖
256
size_max: ReferenceListProperty❖

Maximum size of the widget.

References

This attribute groups the following referenced properties:

Default value❖
(256, 256)
update_text(text: str, markup: bool = False) → None❖

Update the tooltip’s displayed text.

update_size() → None❖

Recalculate the widget’s size based on its current content.