Update README.md
This commit is contained in:
208
README.md
208
README.md
@@ -1,3 +1,209 @@
|
||||
# ThunderPing
|
||||
|
||||
ThunderPing is a system tray applet that monitors Thunderbird unread emails and notifies you with a dynamic colored icon.
|
||||
ThunderPing is a system tray applet that monitors Thunderbird unread emails and notifies you with a dynamic colored icon.
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- 🎯 **Unread email monitoring** - Counts unread emails directly from Thunderbird MSF files
|
||||
- 🎨 **Dynamic colored icons** - Each account can have its distinctive color
|
||||
- 🌍 **Multilingual** - Support for Italian and English with automatic language detection
|
||||
- ⚙️ **Simple configuration** - Intuitive GUI for settings and colors
|
||||
- 🚀 **Automatic startup** - Can be configured to start at system login
|
||||
- 🎨 **Integrated color picker** - Double-click to easily select account colors
|
||||
- 📊 **Badge support** - Number badges with AppIndicator integration
|
||||
- 🔄 **Real-time updates** - Configurable refresh intervals
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
### Automatic installation
|
||||
```bash
|
||||
chmod +x install.sh
|
||||
./install.sh
|
||||
```
|
||||
|
||||
### Manual installation
|
||||
1. Make sure you have Python 3 and GTK 3 installed
|
||||
2. Copy files to desired directory
|
||||
3. Compile translations: `./utils/update-translations.sh`
|
||||
4. Run: `python3 src/applet.py`
|
||||
|
||||
## 🎮 Usage
|
||||
|
||||
1. **Start**: Run `python3 src/applet.py` or search for "ThunderPing" in applications menu
|
||||
2. **Configuration**: Right-click on system tray icon → ⚙ Settings
|
||||
3. **Account colors**: In "Accounts" tab, double-click on an account to change color
|
||||
4. **Autostart**: Enable "Start with system" for automatic startup
|
||||
|
||||
## 🌍 Supported Languages
|
||||
|
||||
- 🇮🇹 **Italian** (automatic detection)
|
||||
- 🇬🇧 **English** (fallback and automatic detection)
|
||||
|
||||
### Language testing
|
||||
```bash
|
||||
# Test Italian
|
||||
LANG=it_IT.UTF-8 python3 src/applet.py
|
||||
|
||||
# Test English
|
||||
LANG=en_US.UTF-8 python3 src/applet.py
|
||||
```
|
||||
|
||||
## 🔧 Adding New Translations
|
||||
|
||||
To add support for a new language:
|
||||
|
||||
1. **Add translatable strings in code** using `_("Your string")`:
|
||||
```python
|
||||
label = Gtk.Label(label=_("Your new text"))
|
||||
```
|
||||
|
||||
2. **Update translation files**:
|
||||
```bash
|
||||
cd utils/
|
||||
./update-translations.sh
|
||||
```
|
||||
|
||||
3. **Create new language directory**:
|
||||
```bash
|
||||
mkdir -p locale/[LANG_CODE]/LC_MESSAGES/
|
||||
cp locale/en/LC_MESSAGES/thunderping.po locale/[LANG_CODE]/LC_MESSAGES/
|
||||
```
|
||||
|
||||
4. **Translate the .po file**:
|
||||
```po
|
||||
msgid "Your new text"
|
||||
msgstr "Your translation"
|
||||
```
|
||||
|
||||
5. **Compile translations**:
|
||||
```bash
|
||||
./update-translations.sh
|
||||
```
|
||||
|
||||
6. **Update language detection** in `src/applet.py`:
|
||||
```python
|
||||
if lang not in ['it', 'en', 'your_lang']:
|
||||
lang = 'en' # Add your language code
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
Configuration file is located at `~/.config/thunderping/config.json` and includes:
|
||||
|
||||
- Update interval (seconds)
|
||||
- Tooltip font size
|
||||
- Custom colors for each account
|
||||
- Autostart settings
|
||||
- Multi-account and single-account default colors
|
||||
|
||||
### Configuration structure
|
||||
```json
|
||||
{
|
||||
"accounts": [
|
||||
{
|
||||
"enabled": true,
|
||||
"name": "account_name",
|
||||
"displayName": "Display Name",
|
||||
"msf_path": "/path/to/INBOX.msf",
|
||||
"profile_name": "default",
|
||||
"color": "#FF0000"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
### Update translations
|
||||
```bash
|
||||
./utils/update-translations.sh
|
||||
```
|
||||
|
||||
### Project structure
|
||||
```
|
||||
thunderping/
|
||||
├── src/
|
||||
│ ├── applet.py # Main application
|
||||
│ └── generate_config.py # Configuration generator
|
||||
├── utils/
|
||||
│ └── update-translations.sh # Translation management
|
||||
├── locale/
|
||||
│ ├── en/LC_MESSAGES/ # English translations
|
||||
│ └── it/LC_MESSAGES/ # Italian translations
|
||||
├── translations/
|
||||
│ └── thunderping.pot # Translation template
|
||||
├── img/
|
||||
│ ├── ThunderPing.png # Application icon (PNG)
|
||||
│ └── ThunderPing.svg # Application icon (SVG)
|
||||
├── install.sh # Automatic installation script
|
||||
├── uninstall.sh # Uninstallation script
|
||||
└── README.md # Project documentation
|
||||
```
|
||||
|
||||
## 📋 Requirements
|
||||
|
||||
- Python 3.6+
|
||||
- GTK 3
|
||||
- PyGObject (gi)
|
||||
- Cairo
|
||||
- AppIndicator3 (optional, falls back to StatusIcon)
|
||||
- Thunderbird (for email monitoring)
|
||||
|
||||
### Ubuntu/Debian
|
||||
```bash
|
||||
sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0 gir1.2-appindicator3-0.1
|
||||
```
|
||||
|
||||
### Fedora
|
||||
```bash
|
||||
sudo dnf install python3-gobject gtk3-devel libappindicator-gtk3-devel
|
||||
```
|
||||
|
||||
## 🖥️ Compatibility
|
||||
|
||||
**Developed and tested on:**
|
||||
- **Linux Mint 22** with Cinnamon desktop environment
|
||||
- **Python 3.12**
|
||||
- **GTK 3.24**
|
||||
|
||||
**Should work on most Linux distributions with:**
|
||||
- GTK 3.6+ and PyGObject support
|
||||
- AppIndicator3 support (GNOME, Unity, Cinnamon, MATE, etc.)
|
||||
- Falls back to StatusIcon for unsupported desktop environments
|
||||
|
||||
**Notes:**
|
||||
- Icon cache refresh may be needed after installation on some desktop environments
|
||||
- The custom application icon is automatically installed and managed by the installation script
|
||||
|
||||
## 🗑️ Uninstallation
|
||||
|
||||
```bash
|
||||
./uninstall.sh
|
||||
```
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
- ThunderPing reads Thunderbird `.msf` files directly without interfering with the email client
|
||||
- Icon changes color dynamically based on unread email count and configured colors
|
||||
- Supports multiple accounts with color inheritance from defaults
|
||||
- Uses AppIndicator when available, falls back to GTK StatusIcon for compatibility
|
||||
- The application launcher uses a custom PNG icon automatically installed in `~/.local/share/thunderping/`
|
||||
- System tray icon is dynamically generated with unread count badges and account-specific colors
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
**If ThunderPing doesn't detect your accounts:**
|
||||
1. Make sure Thunderbird is configured and has created profiles
|
||||
2. Verify that `.msf` files exist in the profile directory
|
||||
3. Check startup logs for any errors
|
||||
4. Run configuration generator: `python3 src/generate_config.py`
|
||||
|
||||
### Common issues
|
||||
- **No icon in system tray**: Install AppIndicator3 or use a desktop environment that supports system tray
|
||||
- **Translations not working**: Run `./utils/update-translations.sh` and restart the application
|
||||
- **Account not detected**: Check if the MSF file path is correct in the configuration
|
||||
- **Application icon not updated**: Clear icon cache with `gtk-update-icon-cache -f -t ~/.local/share/icons/ 2>/dev/null || echo "No local icon cache to update"` or restart desktop environment
|
||||
|
||||
## 🆓 License
|
||||
This project is released under GPL v3 license. Feel free to modify it, improve it, or make it even more useless than it already is.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user