CTkToolTipPro 1.0.0
Advanced tooltip widget for CustomTkinter.
License: MIT
Requires Python: >=3.8
Keywords: customtkinter tooltip gui widget tkinter

# CTkToolTipPro

CTkToolTipPro is a fully customizable tooltip widget built for CustomTkinter, supporting smart hover effects, shadow, auto-close, transparency, theme-aware colors, rounded corners, border styling, font control, delay configuration, cursor tracking, and polished modern UX.

---

## Overview

**CTkToolTipPro** is a highly customizable and modern tooltip widget designed to enhance CustomTkinter GUI applications.  
It supports transparency, shadow effects, auto-close timers, adaptive positioning, and light/dark mode compatibility, making tooltips both functional and visually appealing.

---

## Features

| Feature         | Description                                                                                  | Supported Platforms            |
|-----------------|----------------------------------------------------------------------------------------------|-------------------------------|
| Tooltip on Hover| Displays a tooltip when the mouse hovers over a widget.                                     | Windows, macOS, Linux          |
| Configurable Delay | Delay in seconds before the tooltip appears after hovering.                               | All                           |
| Auto Close      | Automatically hides the tooltip after a configurable time in milliseconds.                  | All                           |
| Follow Cursor   | Tooltip optionally follows the mouse cursor while inside the widget.                        | All                           |
| Transparency    | Supports adjustable alpha transparency for smooth tooltip backgrounds.                      | All                           |
| Shadow Effect   | Adds subtle shadow effect on supported platforms (Windows and macOS).                       | Windows, macOS                |
| Rounded Corners | Customizable corner radius for rounded tooltip edges.                                       | All                           |
| Custom Colors   | Allows customization of background, border, and text colors.                                | All                           |
| Max Width       | Wraps tooltip text to a maximum width to maintain readability.                              | All                           |
| Custom Fonts    | Supports setting custom font family, size, and style for tooltip text.                      | All                           |

---

## Installation

Install via pip:

```bash
pip install CTkToolTipPro
```

Or install from source:

```bash
git clone https://github.com/yourusername/CTkToolTipPro.git
cd CTkToolTipPro
pip install .
```

---

## Usage Example

```python
import customtkinter as ctk
from CTkToolTipPro import CTkToolTipPro

def main():
    app = ctk.CTk()
    app.geometry("400x200")

    button = ctk.CTkButton(app, text="Hover me")
    button.pack(pady=50)

    tooltip = CTkToolTipPro(
        widget=button,
        message="Advanced tooltip for CustomTkinter with shadow and auto-close.",
        delay=0.5,
        auto_close=3000,
        corner_radius=8,
        border_width=1,
        border_color="#555555",
        bg_color="#333333",
        text_color="#ffffff",
        font=("Arial", 12, "bold"),
        max_width=250,
        shadow=True,
    )

    app.mainloop()

if __name__ == "__main__":
    main()
```

---

## API Reference

### `CTkToolTipPro` class

**Parameters:**

| Parameter      | Type           | Description                                      | Default       |
|----------------|----------------|------------------------------------------------|---------------|
| `widget`       | tkinter widget | Target widget to attach the tooltip             | None          |
| `message`      | str            | Tooltip text                                    | None          |
| `delay`        | float          | Delay in seconds before tooltip appears         | 0.2           |
| `follow`       | bool           | Tooltip follows mouse inside widget              | True          |
| `x_offset`     | int            | Horizontal offset from mouse pointer             | 20            |
| `y_offset`     | int            | Vertical offset from mouse pointer               | 10            |
| `bg_color`     | str            | Background color                                 | Theme default |
| `corner_radius`| int            | Corner radius for tooltip background             | 10            |
| `border_width` | int            | Border width                                     | 0             |
| `border_color` | str            | Border color                                     | None          |
| `alpha`        | float          | Transparency level (0 to 1)                      | 0.95          |
| `padding`      | tuple          | Padding inside tooltip (x, y)                     | (10, 2)       |
| `font`         | tuple or None  | Font tuple `(family, size, style)`                | None          |
| `text_color`   | str or None    | Text color                                       | Theme default |
| `max_width`    | int            | Max width of tooltip text for wrapping           | 300           |
| `auto_close`   | int or None    | Time in ms to auto close tooltip, None disables  | None          |
| `shadow`       | bool           | Enable shadow effect (Windows/macOS only)        | True          |

**Key Methods:**

| Method           | Description                                  |
|------------------|----------------------------------------------|
| `.show()`        | Enable the tooltip if disabled                |
| `.hide()`        | Hide and disable the tooltip                   |
| `.configure()`   | Update tooltip message, colors, font, etc.    |
| `.get()`         | Get current tooltip message text               |
| `.is_disabled()` | Check if tooltip is currently disabled         |

---

## License

This project is licensed under the terms of the [MIT License](LICENSE).