Metadata-Version: 2.4
Name: LightTray
Version: 1.0.0
Summary: A Windows system tray icon library
Home-page: https://github.com/kowxp12/LightTray
Author: kowxp
Author-email: Your Name <your.email@example.com>
License: MIT
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🧾 LightTray

**LightTray** is a lightweight, pure-Python library for creating and managing system tray icons on Windows.  
No external GUI frameworks, no heavy dependencies — just your icon, your menu, and your code.

---

## ✨ Features

- 🖼️ **Simple API** — create a tray icon in 3 lines of code
- 🖱️ **Event-driven** — handle left/right clicks, double-clicks, and context menus
- 📋 **Rich menus** — submenus, separators, checkmarks, enable/disable items
- 🔔 **Notifications** — balloon tips with info, warning, and error icons
- 🎨 **Custom icons** — load from `.ico`, `.png`, `.jpg`, `.bmp`, or `PIL.Image`
- 🧩 **No external GUI** — runs purely on Windows API via `ctypes`
- 🚀 **Lightweight** — minimal memory footprint, no extra threads (unless you need them)

---

## 📦 Installation

### From PyPI
```bash
pip install LightTray
```

From source

```bash
git clone https://github.com/kowxp12/LightTray.git
cd LightTray
pip install -e .
```

Manual requirements

LightTray requires Pillow for image processing. It will be installed automatically, but you can also install it manually:

```bash
pip install Pillow>=9.0.0
```

---

🚀 Quick Start

```python
from LightTray import Tray, menu_item, TrayEvent, NotificationIcon

# Create a tray icon
tray = Tray("icon.png", "My Awesome App")

# Add a click handler
tray.on_click(TrayEvent.LEFT_CLICK, lambda: print("Hello from tray!"))

# Build a menu
tray.set_menu([
    menu_item("Open", lambda: print("Opening..."), style=MenuItemStyle.BOLD),
    menu_item("Save", lambda: print("Saved!")),
    menu_item("-", style=MenuItemStyle.SEPARATOR),
    menu_item("Exit", lambda: tray.stop())
])

# Show a notification
tray.show_notification("Welcome!", "Right-click the icon for menu.", NotificationIcon.INFO)

# Run the tray (blocks until exit)
tray.run()
```

---

📖 Documentation

🧩 Core Class: Tray

```python
tray = Tray(icon_source, tooltip="My App", config=None)
```

Parameter Type Description
icon_source str or PIL.Image Path to icon file or PIL Image object
tooltip str Hover text shown over the tray icon
config TrayConfig Optional advanced configuration

---

🎯 Events

```python
tray.on_click(TrayEvent.LEFT_CLICK, callback)
tray.on_click(TrayEvent.RIGHT_CLICK, callback)
tray.on_click(TrayEvent.DOUBLE_CLICK, callback)
tray.on_click(TrayEvent.CONTEXT_MENU, callback)
```

Event Description
LEFT_CLICK Single left-click on the icon
RIGHT_CLICK Single right-click (usually shows menu)
DOUBLE_CLICK Double left-click
CONTEXT_MENU Context menu request (usually right-click)

---

📋 Menus

```python
tray.set_menu([
    menu_item("Label", callback, style=MenuItemStyle.NORMAL),
    menu_item("-", style=MenuItemStyle.SEPARATOR),
    submenu("Submenu", [
        menu_item("Item 1", callback1),
        menu_item("Item 2", callback2),
    ]),
])
```

Style Description
NORMAL Regular clickable item
BOLD Bold text (default action)
CHECKED Item with a checkmark
DISABLED Grayed out, unclickable
SEPARATOR Horizontal line

---

🔔 Notifications

```python
tray.show_notification(
    title="Hello",
    message="This is a notification!",
    icon=NotificationIcon.INFO,
    timeout_ms=5000
)
```

Icon Description
INFO Blue "i" icon
WARNING Yellow exclamation mark
ERROR Red "X" icon
NONE No icon

---

⚙️ Advanced Configuration

```python
from LightTray import TrayConfig

config = TrayConfig()
config.icon_size = (32, 32)
config.use_modern_version = True
config.callback_message = 0x0400 + 1

tray = Tray("icon.png", "App", config)
```

---

🛠️ Full Example

```python
from LightTray import Tray, menu_item, submenu, TrayEvent, NotificationIcon, MenuItemStyle
from PIL import Image

# Load an image from file
img = Image.open("my_icon.png")

# Create tray
tray = Tray(img, "My Application")

# Event handlers
tray.on_click(TrayEvent.LEFT_CLICK, lambda: print("Left click!"))
tray.on_click(TrayEvent.DOUBLE_CLICK, lambda: tray.show_notification(
    "Hello!", "You double-clicked the icon!", NotificationIcon.INFO
))

# Advanced menu
tray.set_menu([
    menu_item("📂 Open Project", lambda: print("Opening..."), style=MenuItemStyle.BOLD),
    menu_item("💾 Save", lambda: print("Saved!")),
    menu_item("🔄 Refresh", lambda: print("Refreshing...")),
    menu_item("-", style=MenuItemStyle.SEPARATOR),
    submenu("⚙️ Settings", [
        menu_item("Theme", lambda: print("Theme changed")),
        menu_item("Language", lambda: print("Language changed")),
        menu_item("-", style=MenuItemStyle.SEPARATOR),
        menu_item("Reset", lambda: print("Reset to defaults")),
    ]),
    menu_item("-", style=MenuItemStyle.SEPARATOR),
    menu_item("❌ Exit", lambda: tray.stop())
])

# Run it
tray.run()
```

---

📝 Notes

· Windows only — LightTray uses Windows API directly and will not work on macOS or Linux.
· WNDPROC reference — The underlying ctypes callback must stay alive. The Tray class handles this automatically.
· Pillow required — Needed for PNG, JPG, and other image formats. ICO files work without it.

---

🐛 Troubleshooting

ImportError: "LightTray is a Windows-only package"

You're running on a non-Windows OS. LightTray only works on Windows.

"Failed to load icon from image"

Make sure:

· The image file exists and is accessible
· The image is in a supported format (PNG, ICO, JPG, BMP)
· Pillow is installed: pip install Pillow

Tray icon not showing up

Try:

· Running your script as administrator
· Restarting Windows Explorer (taskkill /f /im explorer.exe && explorer.exe)

---

📄 License

MIT License — feel free to use, modify, and distribute.

---

🤝 Contributing

Contributions are welcome! Feel free to open issues, submit PRs, or suggest features.

---

🧑‍💻 Author

kowxp
GitHub: @kowxp12
Email: kowxpip333@gmail.com

---

⭐ Star This Project

If you find LightTray useful, please give it a ⭐ on GitHub!

```
