Color Notify

A desktop notification tool that detects color codes in your clipboard and displays beautiful growl-style notifications with the detected color as background. Now includes an integrated Color Picker dialog for manual color selection!

✨ Features

Clipboard Monitoring

• 🎨 Auto-detect color codes - Supports HEX (#FF0000, #F00) and RGB (rgb(255, 0, 0))
• 🔔 Growl-style notifications - Frameless, borderless, with smooth fade animations
• 📍 Flexible positioning - 9 positions: left/center/right × up/center/down
• 👁️ Adjustable transparency - Opacity from 0.0 to 1.0
• ⏱️ Configurable timeout - Auto-hide after specified time or keep visible (0 = no auto-hide)

Color Picker Dialog

• 🎨 Interactive color picker - Qt color dialog integration
• 📍 Smart positioning - Color dialog opens next to picker (configurable: left/right/top/bottom)
• 🎯 Smart focus management - Focus returns to previous window on Escape
• ⚙️ Auto-hide option - Optionally close picker after color selection
• ⌨️ Global shortcut - Ctrl+Alt+Shift+C to open from anywhere
• 💾 Auto-copy to clipboard - Selected colors automatically copied
• 🔍 Hex input support - Manually enter hex color codes
• ⌨️ Keyboard shortcuts - Quick access with hotkeys
• 📺 Always on top - Toggle with keyboard shortcuts
• 🔄 Live clipboard detection - Auto-updates from clipboard

System Integration

• ⚙️ INI configuration - All settings in .color-notify.ini or color-notify.ini
• 🖥️ System tray integration - Background monitoring with tray menu
• 🔝 Always on Top - Optional AOT mode
• 🌈 Smart text color - Auto black/white text based on luminance
• ⏸️ Pause/Resume - Toggle monitoring from tray menu
• 🖱️ Click to dismiss - Click notification to close it

📦 Installation

pip install color-notify

Requirements

• Python 3.6+
• PyQt5
• pynput (for global hotkey support)

Note: The global hotkey Ctrl+Alt+Shift+C requires pynput. If not installed, you can still use the tray menu to access the color picker.

🚀 Usage

Run the application

color-notify

Or run as Python module:

python -m color_notify

The application will start in the background with a system tray icon.

Clipboard Monitoring Mode

1. Copy a color code to your clipboard:

   • #FF5733
   • #F00
   • rgb(255, 87, 51)
   • rgb(100, 200, 150)

2. A notification will appear with the color as background!

Color Picker Mode

1. Right-click the tray icon and select "🎨 Color Picker"

   OR

   Press global shortcut: Ctrl+Alt+Shift+C (from anywhere!)

2. Use the color picker dialog to:

   • Click "Choose Color" to open Qt color dialog
   • Type hex code in input field and press Enter
   • Selected color automatically copied to clipboard

Color Picker Keyboard Shortcuts

• Ctrl+Alt+Shift+C - Open color picker (global shortcut)
• Q or Escape - Close color picker
• A - Enable always on top
• Shift + A - Disable always on top
• Enter - Set color from hex input

⚙️ Configuration

Color Notify looks for configuration in:

1. ~/.color-notify.ini (user home directory) - Recommended
2. color-notify.ini (current directory) - Fallback

Create or edit the configuration file:

[notification]
# Position: left_up, left_center, left_down,
#           center_up, center_center, center_down,
#           right_up, right_center, right_down
position = right_center

# Transparency (0.0 - 1.0)
opacity = 0.95

# Keep notification always on top
always_on_top = True

# Auto-hide timeout in milliseconds
# 0 = no auto-hide (stays until clicked)
timeout = 3000

# Margin from screen edge in pixels
margin = 20

# Enable notification sound (not implemented yet)
sound_enabled = False

[color_picker]
# Position of Qt Color Dialog relative to Color Picker
# Options: left, right, top, bottom
color_dialog_position = right

# Auto-hide Color Picker after selecting a color
# True = Closes picker and returns to previous window
# False = Keeps picker open for multiple picks (default)
auto_hide_after_pick = False

[detection]
# Detect HEX format (#FF0000, #F00)
detect_hex = True

# Detect RGB format (rgb(255, 0, 0))
detect_rgb = True

# Detect HSL format (not implemented yet)
detect_hsl = False

# Clipboard polling interval in milliseconds
# Lower = more responsive but may cause clipboard conflicts on Windows
# Recommended: 1000-2000ms for Windows, 500-1000ms for Linux/macOS
poll_interval = 1000

Note for Windows Users: If you see clipboard warning messages, increase poll_interval to 1500-2000ms in the config file. This prevents conflicts with other clipboard applications.

Quick Config Access

Right-click the tray icon and select "Open Config File" to edit settings.

🎯 System Tray Menu

• 🎨 Color Picker (Ctrl+Alt+Shift+C) - Open color picker dialog
• 🧪 Test Notification - Display a random color notification
• ⏸️ Pause/Resume Monitoring - Toggle clipboard monitoring
• 🔄 Reload Config - Reload configuration without restart
• ⚙️ Open Config File - Open config file in default editor
• ℹ️ About - Show application information
• ❌ Exit - Close the application

📸 What You'll See

Notifications Display:

• Title: Color type and code (HEX/RGB)
• Body:
  • RGB values
  • Brightness classification (LIGHT/DARK)
  • Luminance value and visual bar
• Background: The detected color
• Text: Auto-adjusted (black/white) for readability

Color Picker Shows:

• Color Preview - Large preview box with current color
• Color Name - Hex code display
• Choose Color Button - Opens Qt color dialog
• Set Color Button - Apply hex from input field
• Hex Input - Manual hex code entry

Color Notify - Complete Features Overview

🎯 Two Operating Modes

1. Passive Mode - Clipboard Monitoring

Automatically detects and displays colors from clipboard.

How it works:

• Monitors clipboard continuously
• Detects color codes automatically
• Shows growl-style notification
• No user interaction needed

Supported formats:

• HEX: #FF0000, #F00
• RGB: rgb(255, 0, 0)

2. Active Mode - Color Picker

Interactive dialog for manual color selection.

How it works:

• Open from system tray
• Pick colors interactively
• Auto-copy to clipboard
• Full dialog interface

Features:

• Qt color dialog integration
• Manual hex input
• Live clipboard detection
• Always on top option

📋 Complete Feature List

Clipboard Monitoring Features

Notification Features

Color Picker Features

System Tray Features

Configuration Features

Error Handling Features

🎨 Color Format Support

Currently Supported

HEX Formats

• 6-digit: #FF5733 (red, green, blue)
• 3-digit: #F00 (expands to #FF0000)
• Case insensitive: #ff5733 = #FF5733

RGB Formats

• Standard: rgb(255, 87, 51)
• Spaces: rgb( 255 , 87 , 51 )
• Case insensitive: RGB(255,87,51)
• Validated: 0-255 range checking

Planned Support

• HSL: hsl(9, 100%, 60%)
• HSLA: hsla(9, 100%, 60%, 1.0)
• RGBA: rgba(255, 87, 51, 1.0)
• Named colors: red, blue, etc.
• CSS color keywords

🎯 Position Options

All 9 screen positions available:

left_up      center_up      right_up
left_center  center_center  right_center
left_down    center_down    right_down

Each respects margin setting for distance from screen edge.

⏱️ Timeout Behavior

🎨 Smart Features

Luminance-Based Text Color

• Light colors (luminance > 0.5): Black text
• Dark colors (luminance ≤ 0.5): White text
• Ensures readability on any background

Luminance Calculation

luminance = (0.299 × R + 0.587 × G + 0.114 × B) / 255

Visual Luminance Bar

• 20-character bar: ████████████████████
• Length based on luminance value
• Quick visual brightness indicator

🔄 Workflow Integration

Design Workflow

Design Tool → Copy Color → Notification → Verify
     ↓
Color Picker → Choose → Auto Copy → Paste

Development Workflow

Code → Copy Color → Notification → Check
    ↓
Color Picker → Test → Copy → Implement

Testing Workflow

Spec → Color Picker → Choose → Compare → Verify
         ↓
  Notification confirms copied colors

🚀 Performance

Resource Usage

• Memory: ~50-100 MB
• CPU: <1% idle, <5% active
• Startup: <2 seconds

Optimization

• Efficient clipboard polling
• Error-based interval adjustment
• Minimal background operations
• No unnecessary rendering

🔒 Security & Privacy

What We Access

• ✅ System clipboard (text only)
• ✅ System tray
• ✅ Config file (local)

What We Don't

• ❌ No network access
• ❌ No file scanning
• ❌ No data collection
• ❌ No telemetry

Data Storage

• Config file only (~/.color-notify.ini)
• No color history saved
• No tracking or analytics
• Fully local operation

🎯 Use Case Matrix

💡 Best Practices

For Designers

1. Keep Color Picker open while designing
2. Use Always on Top (A key)
3. Enable notifications for verification
4. Set timeout to 5000 for longer viewing

For Developers

1. Use notifications to verify copied colors
2. Quick color picker for testing
3. Set poll interval to 1000 for responsiveness
4. Position notifications away from editor

For QA/Testing

1. Use both modes for comprehensive checks
2. Color Picker for spec comparison
3. Notifications for automated checks
4. Save screenshots with notifications

🔮 Future Enhancements

Planned Features

• HSL/HSV format support
• Color history log
• Palette management
• Gradient picker
• Color harmonies
• Contrast checker
• Export to formats (CSS, JSON, etc.)
• Multiple color detection in single clipboard
• Notification templates
• Sound notifications
• Statistics tracking

Community Requests

Submit feature requests on GitHub Issues

📊 Feature Comparison

vs Manual Copy-Paste

vs Browser Extensions

vs Color Picker Apps

🔧 Examples

HEX Colors

#FF0000  → Red
#00FF00  → Green
#0000FF  → Blue
#FFFF00  → Yellow
#FF00FF  → Magenta
#00FFFF  → Cyan
#F0A500  → Orange
#9B59B6  → Purple

RGB Colors

rgb(255, 0, 0)      → Red
rgb(0, 255, 0)      → Green
rgb(100, 150, 200)  → Light Blue
rgb(255, 87, 51)    → Coral

Short HEX

#F00  → Red (#FF0000)
#0F0  → Green (#00FF00)
#00F  → Blue (#0000FF)

💡 Use Cases

For Designers

• Quick color reference from design files
• Pick colors interactively with color picker
• Verify colors from screenshots
• Check accessibility (luminance display)
• Build color palettes

For Developers

• Monitor colors from code
• Verify hex/rgb conversions
• Quick color validation
• Copy colors to clipboard instantly
• Test color combinations

For QA/Testing

• Verify UI colors match specs
• Document color usage
• Cross-reference design systems
• Quick color comparisons

🛠️ Development

Requirements

• Python 3.6+
• PyQt5

Troubleshooting

Clipboard warnings on Windows?

• Increase poll_interval to 1500-2000ms in config
• See TROUBLESHOOTING.md for details

Color Picker not showing?

• Check system tray menu is accessible
• Try running from command line to see errors

For more help, check:

• TROUBLESHOOTING.md - Detailed troubleshooting guide
• INSTALL.md - Installation help
• QUICKSTART.md - Quick start guide

Local Development

# Clone repository
git clone https://github.com/cumulus13/color-notify.git
cd color-notify

# Install in development mode
pip install -e .

# Run
python -m color_notify

🎨 Two Modes of Operation

1. Passive Mode (Default)

• Monitors clipboard automatically
• Shows notifications when colors detected
• Runs in background

2. Active Mode (Color Picker)

• Manual color selection
• Interactive color dialog
• Instant clipboard copy
• Always accessible from tray menu

Both modes work together seamlessly!

📝 License

MIT License - see LICENSE file for details

👤 Author

Hadi Cahyadi

Support me on Patreon

🔗 Links

• GitHub: https://github.com/cumulus13/color-notify
• PyPI: https://pypi.org/project/color-notify/
• Issues: https://github.com/cumulus13/color-notify/issues

🤝 Contributing

Contributions, issues, and feature requests are welcome!

Feel free to check the issues page.

⭐ Show Your Support

Give a ⭐️ if this project helped you!

📊 Changelog

Version 1.0.1

• ✨ Added Color Picker Dialog
• 🎨 Interactive color selection
• ⌨️ Keyboard shortcuts for color picker
• 🔄 Live clipboard detection in picker
• 🐛 Fixed clipboard access warnings on Windows
• 📈 Improved error handling
• 📝 Better documentation

Version 1.0.0

• 🎉 Initial release
• 🎨 HEX and RGB color detection
• 🔔 Growl-style notifications
• 🖥️ System tray integration
• ⚙️ Configurable positioning and timeout
• ⏸️ Pause/Resume monitoring
• 🖱️ Click to dismiss notifications

Enjoy Color Notify! 🎨✨