tooltip

_tooltip ¶

Rich, theme-aware tooltip widget.

Classes:

Name	Description
`FXTooltip`	A rich, theme-aware tooltip with advanced features.
`FXTooltipManager`	Global manager that intercepts standard Qt tooltips and shows FXTooltip instead.
`FXTooltipPosition`	Tooltip position relative to anchor widget.

Functions:

Name	Description
`set_tooltip`	Attach an FXTooltip to a widget or item with a simple API.

FXTooltip ¶

FXTooltip(
    parent: Optional[QWidget] = None,
    title: Optional[str] = None,
    description: str = "",
    icon: Optional[str] = None,
    image: Optional[QPixmap] = None,
    shortcut: Optional[str] = None,
    action_text: Optional[str] = None,
    action_callback: Optional[Callable] = None,
    position: FXTooltipPosition = AUTO,
    show_delay: int = 500,
    hide_delay: int = 200,
    duration: int = 0,
    persistent: bool = False,
    show_arrow: bool = True,
    max_width: int = 300,
)

Bases: FXThemeAware, QFrame


              flowchart TD
              fxgui.fxwidgets._tooltip.FXTooltip[FXTooltip]
              fxgui.fxstyle.FXThemeAware[FXThemeAware]

                              fxgui.fxstyle.FXThemeAware --> fxgui.fxwidgets._tooltip.FXTooltip
                


              click fxgui.fxwidgets._tooltip.FXTooltip href "" "fxgui.fxwidgets._tooltip.FXTooltip"
              click fxgui.fxstyle.FXThemeAware href "" "fxgui.fxstyle.FXThemeAware"

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_at_point`	Show tooltip at a specific global position.
`show_at_rect`	Show tooltip positioned relative to a global rectangle.
`show_for_rect`	Convenience method to show a tooltip for a screen rectangle.
`show_for_widget`	Convenience method to show a tooltip for a widget.
`show_tooltip`	Programmatically show the tooltip.

Functions¶

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_at_point ¶

show_at_point(global_pos: QPoint, position: FXTooltipPosition = BOTTOM) -> None

Show tooltip at a specific global position.

The tooltip will be positioned relative to the given point, treating it as a zero-size anchor.

Parameters:

Name	Type	Description	Default
`global_pos` ¶	`QPoint`	Global (screen) coordinates where tooltip should appear.	required
`position` ¶	`FXTooltipPosition`	Which direction the tooltip should extend from the point.	`BOTTOM`

Examples:

>>> # Show tooltip at cursor position
>>> tooltip.show_at_point(QCursor.pos())
>>>
>>> # Show tooltip below a specific point
>>> tooltip.show_at_point(some_global_point, FXTooltipPosition.BOTTOM)

show_at_rect ¶

show_at_rect(rect: QRect, position: Optional[FXTooltipPosition] = None) -> None

Show tooltip positioned relative to a global rectangle.

This is useful for showing tooltips relative to tree items, table cells, or other sub-widget regions that aren't QWidget instances.

Parameters:

Name	Type	Description	Default
`rect` ¶	`QRect`	Rectangle in global (screen) coordinates to position relative to.	required
`position` ¶	`Optional[FXTooltipPosition]`	Optional position override. Uses instance position if None.	`None`

Examples:

>>> # Show tooltip for a tree item
>>> item_rect = tree.visualItemRect(item)
>>> global_rect = QRect(
...     tree.viewport().mapToGlobal(item_rect.topLeft()),
...     item_rect.size()
... )
>>> tooltip.show_at_rect(global_rect)

show_for_rect `staticmethod` ¶

show_for_rect(
    rect: QRect,
    title: Optional[str] = None,
    description: str = "",
    icon: Optional[str] = None,
    shortcut: Optional[str] = None,
    duration: int = 3000,
    position: FXTooltipPosition = AUTO,
    max_width: int = 300,
) -> FXTooltip

Convenience method to show a tooltip for a screen rectangle.

Creates and shows a tooltip immediately, auto-hiding after duration. Useful for tree items, table cells, or other non-widget regions.

Parameters:

Name	Type	Description	Default
`rect` ¶	`QRect`	Rectangle in global (screen) coordinates.	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`
`max_width` ¶	`int`	Maximum width of the tooltip.	`300`

Returns:

Type	Description
`FXTooltip`	The created FXTooltip instance.

Examples:

>>> # Show tooltip for a tree item
>>> item_rect = tree.visualItemRect(item)
>>> global_rect = QRect(
...     tree.viewport().mapToGlobal(item_rect.topLeft()),
...     item_rect.size()
... )
>>> FXTooltip.show_for_rect(
...     global_rect,
...     title="Item Info",
...     description="Details about this item",
...     duration=2000
... )

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.

FXTooltipManager ¶

FXTooltipManager(
    parent: Optional[QObject] = None,
    show_delay: int = 500,
    hide_delay: int = 200,
    max_width: int = 300,
)

Bases: QObject


              flowchart TD
              fxgui.fxwidgets._tooltip.FXTooltipManager[FXTooltipManager]

              

              click fxgui.fxwidgets._tooltip.FXTooltipManager href "" "fxgui.fxwidgets._tooltip.FXTooltipManager"

Global manager that intercepts standard Qt tooltips and shows FXTooltip instead.

This allows you to use the standard widget.setToolTip("text") API and have FXTooltip displayed automatically.

The manager installs an application-wide event filter that intercepts QEvent.ToolTip events and shows an FXTooltip with the widget's tooltip text.

Parameters:

Name	Type	Description	Default
`parent` ¶	`Optional[QObject]`	Parent QObject (typically QApplication.instance()).	`None`
`show_delay` ¶	`int`	Delay in ms before showing tooltip (default 500).	`500`
`hide_delay` ¶	`int`	Delay in ms before hiding tooltip after mouse leaves (default 200).	`200`
`max_width` ¶	`int`	Maximum width of tooltips (default 300).	`300`

Examples:

>>> # Install globally for the entire application
>>> app = QApplication(sys.argv)
>>> FXTooltipManager.install()
>>>
>>> # Now all setToolTip() calls will use FXTooltip
>>> button = QPushButton("Click me")
>>> button.setToolTip("This will show as an FXTooltip!")
>>>
>>> # Uninstall to restore default Qt tooltips
>>> FXTooltipManager.uninstall()

Methods:

Name	Description
`eventFilter`	Intercept tooltip events and show FXTooltip instead.
`install`	Install the global tooltip manager.
`instance`	Get the current tooltip manager instance.
`is_installed`	Check if the tooltip manager is currently installed.
`uninstall`	Uninstall the global tooltip manager.

Functions¶

eventFilter ¶

eventFilter(watched: QObject, event: QEvent) -> bool

Intercept tooltip events and show FXTooltip instead.

install `classmethod` ¶

install(
    show_delay: int = 500, hide_delay: int = 200, max_width: int = 300
) -> FXTooltipManager

Install the global tooltip manager.

After calling this, all widgets using setToolTip() will display FXTooltip instead of the standard Qt tooltip.

Parameters:

Name	Type	Description	Default
`show_delay` ¶	`int`	Delay in ms before showing tooltip.	`500`
`hide_delay` ¶	`int`	Delay in ms before hiding tooltip.	`200`
`max_width` ¶	`int`	Maximum width of tooltips.	`300`

Returns:

Type	Description
`FXTooltipManager`	The installed FXTooltipManager instance.

Examples:

>>> FXTooltipManager.install()
>>> button.setToolTip("Now uses FXTooltip!")

instance `classmethod` ¶

instance() -> Optional[FXTooltipManager]

Get the current tooltip manager instance.

Returns:

Type	Description
`Optional[FXTooltipManager]`	The FXTooltipManager instance, or None if not installed.

is_installed `classmethod` ¶

is_installed() -> bool

Check if the tooltip manager is currently installed.

Returns:

Type	Description
`bool`	True if installed, False otherwise.

uninstall `classmethod` ¶

uninstall() -> None

Uninstall the global tooltip manager.

Restores standard Qt tooltip behavior.

Examples:

>>> FXTooltipManager.uninstall()

FXTooltipPosition ¶

Bases: IntEnum


              flowchart TD
              fxgui.fxwidgets._tooltip.FXTooltipPosition[FXTooltipPosition]

              

              click fxgui.fxwidgets._tooltip.FXTooltipPosition href "" "fxgui.fxwidgets._tooltip.FXTooltipPosition"

Tooltip position relative to anchor widget.

set_tooltip ¶

set_tooltip(
    target: Union[QWidget, QTreeWidgetItem, QListWidgetItem, QTableWidgetItem],
    description: str = "",
    title: Optional[str] = None,
    icon: Optional[str] = None,
    shortcut: Optional[str] = None,
    position: FXTooltipPosition = AUTO,
    show_delay: int = 500,
    hide_delay: int = 200,
) -> FXTooltip

Attach an FXTooltip to a widget or item with a simple API.

This is a convenience function similar to fxicons.set_icon() that creates and attaches an FXTooltip to the given target. The tooltip is automatically shown on hover and hidden when the mouse leaves.

Supports both QWidget subclasses and item-based widgets: - QWidget (buttons, labels, etc.) - QTreeWidgetItem - QListWidgetItem - QTableWidgetItem

Parameters:

Name	Type	Description	Default
`target` ¶	`Union[QWidget, QTreeWidgetItem, QListWidgetItem, QTableWidgetItem]`	The widget or item to attach the tooltip to.	required
`description` ¶	`str`	Main tooltip content text.	`''`
`title` ¶	`Optional[str]`	Optional bold title text.	`None`
`icon` ¶	`Optional[str]`	Optional icon name (from fxicons).	`None`
`shortcut` ¶	`Optional[str]`	Optional keyboard shortcut to display.	`None`
`position` ¶	`FXTooltipPosition`	Preferred position relative to target.	`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`

Returns:

Type	Description
`FXTooltip`	The created FXTooltip instance (kept internally to prevent GC).

Examples:

>>> # Simple tooltip on a button
>>> set_tooltip(button, "Click to save the file")
>>>
>>> # Rich tooltip with all options
>>> set_tooltip(
...     button,
...     description="Save the current document to disk.",
...     title="Save",
...     icon="save",
...     shortcut="Ctrl+S",
... )
>>>
>>> # Tooltip on a tree item
>>> item = QTreeWidgetItem(tree, ["Item 1"])
>>> set_tooltip(
...     item,
...     description="This is a tree item tooltip",
...     title="Item Info",
...     icon="info",
... )

tooltip

_tooltip ¶

Classes¶

FXTooltip ¶

parent ¶

title ¶

description ¶

icon ¶

image ¶

shortcut ¶

action_text ¶

action_callback ¶

position ¶

show_delay ¶

hide_delay ¶

duration ¶

persistent ¶

show_arrow ¶

max_width ¶

Functions¶

enterEvent ¶

eventFilter ¶

hide_tooltip ¶

leaveEvent ¶

mousePressEvent ¶

paintEvent ¶

set_anchor ¶

set_content ¶

show_at_point ¶

show_at_rect ¶

show_for_rect staticmethod ¶

show_for_widget staticmethod ¶

show_tooltip ¶

FXTooltipManager ¶

parent ¶

show_delay ¶

hide_delay ¶

max_width ¶

Functions¶

eventFilter ¶

install classmethod ¶

instance classmethod ¶

is_installed classmethod ¶

uninstall classmethod ¶

FXTooltipPosition ¶

Functions¶

set_tooltip ¶

target ¶

description ¶

title ¶

icon ¶

shortcut ¶

position ¶

show_delay ¶

hide_delay ¶

`parent` ¶

`title` ¶

`description` ¶

`icon` ¶

`image` ¶

`shortcut` ¶

`action_text` ¶

`action_callback` ¶

`position` ¶

`show_delay` ¶

`hide_delay` ¶

`duration` ¶

`persistent` ¶

`show_arrow` ¶

`max_width` ¶

show_for_rect `staticmethod` ¶

show_for_widget `staticmethod` ¶

`parent` ¶

`show_delay` ¶

`hide_delay` ¶

`max_width` ¶

install `classmethod` ¶

instance `classmethod` ¶

is_installed `classmethod` ¶

uninstall `classmethod` ¶

`target` ¶

`description` ¶

`title` ¶

`icon` ¶

`shortcut` ¶

`position` ¶

`show_delay` ¶

`hide_delay` ¶