LightTray 1.0.0

A Windows system tray icon library

🧾 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

pip install LightTray

From source

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:

pip install Pillow>=9.0.0

---

🚀 Quick Start

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

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

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

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

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

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

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: [e-mail]

---

⭐ Star This Project

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