Skip to content

Tooltip

Enhanced tooltips with custom positioning and styling.

Preview

FXTooltip

Classes

FXTooltip

Bases: FXThemeAware, QFrame

A rich, theme-aware tooltip with advanced features.

This widget provides an enhanced tooltip experience with: - Rich content: title, description, icon, images, shortcuts - Smart positioning with arrow pointing to anchor - Theme-aware styling - Fade in/out animations - Hover or programmatic trigger - Configurable delays - Optional action buttons - Persistent mode (stays until clicked away)

Parameters:

Name Type Description Default

parent

Optional[QWidget]

Parent widget (anchor for positioning).

 None

title

Optional[str]

Optional title text (bold).

 None

description

str

Main tooltip content.

 ''

icon

Optional[str]

Optional icon name (from fxicons).

 None

image

Optional[QPixmap]

Optional QPixmap image to display.

 None

shortcut

Optional[str]

Optional keyboard shortcut to display.

 None

action_text

Optional[str]

Optional action button text.

 None

action_callback

Optional[Callable]

Callback for action button click.

 None

position

FXTooltipPosition

Preferred position relative to anchor.

 AUTO

show_delay

int

Delay in ms before showing (default 500).

 500

hide_delay

int

Delay in ms before hiding after mouse leaves (default 200).

 200

duration

int

Auto-hide duration in ms (0 = no auto-hide).

 0

persistent

bool

If True, tooltip stays until explicitly closed.

 False

show_arrow

bool

Whether to show the pointing arrow.

 True

max_width

int

Maximum width of the tooltip.

 300
Signals

shown: Emitted when the tooltip is shown. hidden: Emitted when the tooltip is hidden. action_clicked: Emitted when the action button is clicked.

Examples:

>>> # Simple tooltip attached to a button
>>> tooltip = FXTooltip(
...     parent=my_button,
...     title="Save",
...     description="Save the current file to disk",
...     shortcut="Ctrl+S",
... )
>>>
>>> # Rich tooltip with image and action
>>> tooltip = FXTooltip(
...     parent=my_widget,
...     title="New Feature!",
...     description="Click here to learn about the new export options.",
...     icon="lightbulb",
...     action_text="Learn More",
...     action_callback=lambda: show_help(),
...     persistent=True,
... )
>>>
>>> # Programmatic show/hide
>>> tooltip.show_tooltip()
>>> tooltip.hide_tooltip()

Methods:

Name Description
enterEvent

Handle mouse entering tooltip.
eventFilter

Handle hover events on anchor widget and click-outside detection.
hide_tooltip

Programmatically hide the tooltip.
leaveEvent

Handle mouse leaving tooltip.
mousePressEvent

Handle click to dismiss persistent tooltip.
paintEvent

Paint the tooltip with arrow.
set_anchor

Change the anchor widget.
set_content

Update tooltip content dynamically.
show_for_widget

Convenience method to show a tooltip for a widget.
show_tooltip

Programmatically show the tooltip.

enterEvent 

enterEvent(event) -> None

Handle mouse entering tooltip.

eventFilter 

eventFilter(watched, event) -> bool

Handle hover events on anchor widget and click-outside detection.

hide_tooltip 

hide_tooltip() -> None

Programmatically hide the tooltip.

leaveEvent 

leaveEvent(event) -> None

Handle mouse leaving tooltip.

mousePressEvent 

mousePressEvent(event) -> None

Handle click to dismiss persistent tooltip.

paintEvent 

paintEvent(event) -> None

Paint the tooltip with arrow.

set_anchor 

set_anchor(widget: QWidget) -> None

Change the anchor widget.

Parameters:

Name Type Description Default

widget

QWidget

New anchor widget.

 required

set_content 

set_content(
    title: Optional[str] = None,
    description: Optional[str] = None,
    icon: Optional[str] = None,
    shortcut: Optional[str] = None,
) -> None

Update tooltip content dynamically.

Parameters:

Name Type Description Default

title

Optional[str]

New title text.

 None

description

Optional[str]

New description text.

 None

icon

Optional[str]

New icon name.

 None

shortcut

Optional[str]

New shortcut text.

 None

show_for_widget staticmethod 

show_for_widget(
    widget: QWidget,
    title: Optional[str] = None,
    description: str = "",
    icon: Optional[str] = None,
    shortcut: Optional[str] = None,
    duration: int = 3000,
    position: FXTooltipPosition = AUTO,
) -> FXTooltip

Convenience method to show a tooltip for a widget.

Creates and shows a tooltip immediately, auto-hiding after duration.

Parameters:

Name Type Description Default

widget

QWidget

Widget to show tooltip for.

 required

title

Optional[str]

Optional title.

 None

description

str

Tooltip description.

 ''

icon

Optional[str]

Optional icon name.

 None

shortcut

Optional[str]

Optional shortcut text.

 None

duration

int

Auto-hide duration in ms.

 3000

position

FXTooltipPosition

Tooltip position.

 AUTO

Returns:

Type Description
FXTooltip

The created FXTooltip instance.

Examples:

>>> FXTooltip.show_for_widget(
...     button,
...     title="Tip",
...     description="Click to save",
...     duration=2000
... )

show_tooltip 

show_tooltip() -> None

Programmatically show the tooltip.

FXTooltipPosition

Bases: IntEnum

Tooltip position relative to anchor widget.