Tooltip❖

Module path❖

kivydk.manager.tooltip

Overview❖

TooltipManager tracks pointer movement inside the window and determines whether the cursor is hovering a widget that declares tooltip behavior. When a tooltip-eligible widget is found, the manager selects the correct tooltip widget (custom or default), updates its content, positions it and controls its visibility. Only one tooltip is active at a time.

Reference❖

class TooltipManager(**kwargs)❖

Bases: EventManagerBase, EventDispatcher

Manages detection, creation, reuse, and visibility of tooltip widgets.

The manager alternates between two modes:

Idle mode → a periodic timer checks for tooltip‑eligible widgets.
Active mode → tooltip position and content are updated immediately while the cursor remains over the hovered widget.

tooltip_template: ObjectProperty❖

Default tooltip widget class or instance used when no custom tooltip is provided.

Default value❖

<class 'kivydk.uix.tooltip.Tooltip'>

tooltip_side: OptionProperty❖

Default preferred placement side for positioning the tooltip relative to the hovered widget.

Default value❖

"auto"

tooltip_interactive: BooleanProperty❖

Enable interactive tooltips instead of auto‑hiding hover hints.

Warning

Tooltip interaction is only partially implemented.

The "cursor" tooltip side is partially supported, and "auto" may select "cursor" internally, resulting in same incomplete behavior.

Default value❖

False

tooltip_offset: NumericProperty❖

Default offset between the tooltip and the hovered widget.

Default value❖

edge_offset: VariableListProperty❖

Minimum distance between the tooltip and the window edges.

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

Default value❖

[0, 0, 0, 0]

idle_time: NumericProperty❖

Interval (in seconds) between deep‑search scans for tooltip‑enabled widgets.

The manager checks the hovered widget tree periodically instead of on every mouse movement. If the cursor has not moved since the previous scan, the deep search is skipped to avoid unnecessary work.

Default value❖

0.5

delay_time: NumericProperty❖

Delay (in seconds) before showing a tooltip after a valid hovered widget is detected. This ensures the tooltip appears only when the user is intentionally hovering over the widget, not just passing over it.

Default value❖

1.0

animation_time: NumericProperty❖

Duration (in seconds) of the tooltip fade‑in and fade‑out animations.

The sweet spot is between 0.12 and 0.18.

Default value❖

0.16

stop() → None❖: Deactivate the manager, reset internal references and cancel the clock tasks.

dispatch(etype: str, me: MotionEvent) → bool❖

Process a MotionEvent and update the manager’s state accordingly.

Name	Description
etype	One of `begin`, `update` or `end`.
me	The MotionEvent currently being dispatched.