merged worktrees, task gkt window and gnome extension
This commit is contained in:
buenosairesam
467
docs/README.md
467
docs/README.md
@@ -1,85 +1,436 @@
|
||||
# Deskmeter GNOME Integration - Documentation
|
||||
# Deskmeter OS Integration
|
||||
|
||||
Complete documentation for the Deskmeter GNOME task display tools.
|
||||
Display your current deskmeter task using GNOME Shell extension or standalone GTK window.
|
||||
|
||||
## Documentation Files
|
||||
**Location**: `dmos/` (OS-specific components)
|
||||
|
||||
### Getting Started
|
||||
---
|
||||
|
||||
**[READY_TO_TEST.md](READY_TO_TEST.md)** - ⭐ START HERE
|
||||
Complete testing guide with checklists, troubleshooting, and commands. Everything you need to test both the task window and GNOME extension.
|
||||
## Quick Start
|
||||
|
||||
### Task Window
|
||||
### GTK Task Window (Immediate - No logout)
|
||||
|
||||
**[TASK_WINDOW_README.md](TASK_WINDOW_README.md)**
|
||||
Detailed guide for the standalone GTK task window:
|
||||
- Usage instructions
|
||||
- Configuration options
|
||||
- Startup and autostart setup
|
||||
- Comparison with extension
|
||||
|
||||
### GNOME Extension
|
||||
|
||||
**[INSTALL_STATUS.md](INSTALL_STATUS.md)**
|
||||
Extension installation status and troubleshooting:
|
||||
- Installation checklist
|
||||
- Wayland requirements
|
||||
- Detailed troubleshooting steps
|
||||
- GNOME Looking Glass debugging
|
||||
- Extension file locations
|
||||
|
||||
**[EXTENSION_ORIGINAL.md](EXTENSION_ORIGINAL.md)**
|
||||
Original extension README (kept for reference)
|
||||
|
||||
### Technical Details
|
||||
|
||||
**[PORT_DETECTION_README.md](PORT_DETECTION_README.md)**
|
||||
How automatic port detection works:
|
||||
- Auto-detection mechanism
|
||||
- Manual port configuration
|
||||
- Priority order
|
||||
- Testing and troubleshooting
|
||||
|
||||
## Quick Links
|
||||
|
||||
### Task Window
|
||||
```bash
|
||||
# Run with auto port detection
|
||||
python3 task_window.py
|
||||
python3 dmos/task_window.py
|
||||
|
||||
# Specify port manually
|
||||
python3 task_window.py 10001
|
||||
# Make it always-on-top
|
||||
wmctrl -r "Deskmeter Task" -b add,above,sticky
|
||||
```
|
||||
|
||||
### GNOME Extension
|
||||
### GNOME Extension (Requires logout)
|
||||
|
||||
```bash
|
||||
# Check if enabled
|
||||
cd dmos/gnome-extension
|
||||
./install.sh
|
||||
|
||||
# Enable extension
|
||||
gnome-extensions enable deskmeter-indicator@local
|
||||
|
||||
# Log out and back in (required on Wayland)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Components
|
||||
|
||||
### 1. GTK Task Window (`dmos/task_window.py`)
|
||||
|
||||
Standalone GTK4 window showing current task, always-on-top and visible on all workspaces.
|
||||
|
||||
**Features**:
|
||||
- No window decorations (minimal UI)
|
||||
- Updates every 500ms
|
||||
- Workspace change detection (updates 2.2s after switch)
|
||||
- Auto port detection (tries 10001, then 10000)
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Auto-detect port
|
||||
python3 dmos/task_window.py
|
||||
|
||||
# Specify port
|
||||
python3 dmos/task_window.py 10001
|
||||
|
||||
# Or via environment
|
||||
DESKMETER_PORT=10001 python3 dmos/task_window.py
|
||||
```
|
||||
|
||||
**Window States**:
|
||||
- `Loading...` - Initial state
|
||||
- `work/default` - Current task path
|
||||
- `offline - dmweb not running` (red) - Cannot connect
|
||||
- `error - invalid API response` (orange) - Invalid JSON
|
||||
- `no task` - Valid response, no task set
|
||||
|
||||
**Close**:
|
||||
- `Alt+F4`
|
||||
- `pkill -f task_window.py`
|
||||
|
||||
### 2. GNOME Extension (`dmos/gnome-extension/`)
|
||||
|
||||
Panel indicator integrated into GNOME Shell top bar.
|
||||
|
||||
**Features**:
|
||||
- Native panel integration (left side)
|
||||
- Workspace switch detection with 2.2s debounce
|
||||
- Auto port detection (10001, 10000)
|
||||
- Error handling (won't crash GNOME Shell)
|
||||
- Auto-truncates long paths (shows `.../last/two`)
|
||||
|
||||
**Files**:
|
||||
- `extension.js` - Main extension code
|
||||
- `metadata.json` - Extension metadata (GNOME 40-49)
|
||||
- `stylesheet.css` - Panel styling
|
||||
|
||||
**Installation**:
|
||||
```bash
|
||||
cd dmos/gnome-extension
|
||||
./install.sh # First install
|
||||
# OR
|
||||
./update.sh # After code changes
|
||||
|
||||
# Restart GNOME Shell:
|
||||
# X11: Alt+F2 → 'r' → Enter
|
||||
# Wayland: Log out and back in
|
||||
```
|
||||
|
||||
**Check Status**:
|
||||
```bash
|
||||
# List enabled extensions
|
||||
gnome-extensions list --enabled | grep deskmeter
|
||||
|
||||
# View logs
|
||||
journalctl --user -u org.gnome.Shell@wayland.service -f | grep deskmeter
|
||||
|
||||
# Debug with Looking Glass
|
||||
# Alt+F2 → 'lg' → Extensions tab
|
||||
```
|
||||
|
||||
### API Testing
|
||||
---
|
||||
|
||||
## Port Auto-Detection
|
||||
|
||||
Both components automatically detect dmweb port:
|
||||
|
||||
**Priority Order**:
|
||||
1. Command line argument (window only)
|
||||
2. Environment variable `DESKMETER_PORT` (window only)
|
||||
3. Auto-detection: tries 10001, then 10000
|
||||
|
||||
**Test Ports**:
|
||||
```bash
|
||||
# Test dmweb API
|
||||
curl http://localhost:10001/api/current_task
|
||||
curl http://localhost:10000/api/current_task
|
||||
```
|
||||
|
||||
## Documentation Index
|
||||
**Configure Ports**:
|
||||
```python
|
||||
# In dmos/task_window.py (line 36)
|
||||
DEFAULT_PORTS = [10001, 10000]
|
||||
```
|
||||
|
||||
| File | Purpose | Audience |
|
||||
|------|---------|----------|
|
||||
| READY_TO_TEST.md | Complete testing guide | Everyone - start here |
|
||||
| TASK_WINDOW_README.md | Task window documentation | Window users |
|
||||
| INSTALL_STATUS.md | Extension troubleshooting | Extension users |
|
||||
| PORT_DETECTION_README.md | Port detection details | Advanced users |
|
||||
| EXTENSION_ORIGINAL.md | Original extension docs | Reference |
|
||||
```javascript
|
||||
// In dmos/gnome-extension/deskmeter-indicator@local/extension.js (line 11)
|
||||
const DEFAULT_PORTS = [10001, 10000];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
### Both Components
|
||||
- dmweb Flask server running (`cd dmapp/dmweb && python3 run.py`)
|
||||
- `/api/current_task` endpoint accessible
|
||||
|
||||
### GTK Window
|
||||
- Python 3 with GTK4: `sudo apt install python3-gi gir1.2-gtk-4.0`
|
||||
- wmctrl: `sudo apt install wmctrl`
|
||||
|
||||
### GNOME Extension
|
||||
- GNOME Shell 40-49
|
||||
- Works on X11 and Wayland
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### dmweb Not Running
|
||||
|
||||
```bash
|
||||
# Check if dmweb is running
|
||||
ps aux | grep dmweb
|
||||
|
||||
# Check listening ports
|
||||
ss -tlnp | grep -E "(10000|10001)"
|
||||
|
||||
# Start dmweb
|
||||
cd dmapp/dmweb
|
||||
python3 run.py
|
||||
|
||||
# Test API
|
||||
curl http://localhost:10000/api/current_task
|
||||
# Expected: {"task_id":"abc12345","task_path":"work/default"}
|
||||
```
|
||||
|
||||
### GTK Window Issues
|
||||
|
||||
**"offline - dmweb not running"**:
|
||||
- Start dmweb (see above)
|
||||
|
||||
**Window not staying on top**:
|
||||
```bash
|
||||
wmctrl -r "Deskmeter Task" -b add,above,sticky
|
||||
```
|
||||
|
||||
**GTK4 not found**:
|
||||
```bash
|
||||
sudo apt install python3-gi gir1.2-gtk-4.0
|
||||
```
|
||||
|
||||
**Window doesn't update on workspace change**:
|
||||
```bash
|
||||
# Test wmctrl
|
||||
wmctrl -d
|
||||
# Should show workspaces with * marking current
|
||||
```
|
||||
|
||||
### GNOME Extension Issues
|
||||
|
||||
**Extension not showing in panel**:
|
||||
```bash
|
||||
# Check if enabled
|
||||
gnome-extensions list --enabled | grep deskmeter
|
||||
|
||||
# Re-enable
|
||||
gnome-extensions enable deskmeter-indicator@local
|
||||
|
||||
# View errors
|
||||
journalctl --user -u org.gnome.Shell@wayland.service --since "5 minutes ago" | grep -i deskmeter
|
||||
```
|
||||
|
||||
**Shows "detecting..." forever**:
|
||||
- dmweb not running on 10001 or 10000
|
||||
- Start dmweb and log out/in
|
||||
|
||||
**Shows "offline"**:
|
||||
```bash
|
||||
# Test API endpoint
|
||||
curl http://localhost:10000/api/current_task
|
||||
|
||||
# Check dmweb logs for errors
|
||||
```
|
||||
|
||||
**Changes not appearing after update**:
|
||||
- Ensure `./update.sh` ran successfully
|
||||
- Must restart GNOME Shell (X11) or logout/login (Wayland)
|
||||
- Check logs: `journalctl -f -o cat /usr/bin/gnome-shell`
|
||||
|
||||
---
|
||||
|
||||
## Comparison: Window vs Extension
|
||||
|
||||
| Feature | GTK Window | GNOME Extension |
|
||||
|---------|------------|-----------------|
|
||||
| Visibility | Separate window | Panel indicator |
|
||||
| Screen space | Takes window space | Minimal (panel) |
|
||||
| Setup | Run anytime | Requires logout |
|
||||
| Restart needed | No | Yes (Wayland) |
|
||||
| All workspaces | ✅ (sticky) | ✅ (panel) |
|
||||
| Integration | Standalone | Native GNOME |
|
||||
|
||||
**Use GTK window for**:
|
||||
- Quick testing
|
||||
- No logout required
|
||||
- Temporary usage
|
||||
|
||||
**Use GNOME extension for**:
|
||||
- Permanent setup
|
||||
- Cleaner integration
|
||||
- Less screen clutter
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### GTK Window Settings
|
||||
|
||||
Edit `dmos/task_window.py`:
|
||||
|
||||
```python
|
||||
# Update frequency (line 37)
|
||||
UPDATE_INTERVAL = 2000 # milliseconds
|
||||
|
||||
# Workspace check frequency (line 38)
|
||||
WORKSPACE_CHECK_INTERVAL = 200 # milliseconds
|
||||
|
||||
# Window size (line ~50)
|
||||
self.set_default_size(400, 60) # width x height
|
||||
|
||||
# Font size (line ~27)
|
||||
self.label.set_markup('<span font_desc="14">Loading...</span>')
|
||||
```
|
||||
|
||||
### GNOME Extension Settings
|
||||
|
||||
Edit `dmos/gnome-extension/deskmeter-indicator@local/extension.js`:
|
||||
|
||||
```javascript
|
||||
// Debounce delay (line 10)
|
||||
const DEBOUNCE_DELAY = 2200; // milliseconds
|
||||
|
||||
// Port list (line 11)
|
||||
const DEFAULT_PORTS = [10001, 10000];
|
||||
|
||||
// Update interval (line 12)
|
||||
const UPDATE_INTERVAL = 30000; // 30 seconds
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Auto-start (Optional)
|
||||
|
||||
### GTK Window on Login
|
||||
|
||||
```bash
|
||||
# Create desktop entry
|
||||
cat > ~/.config/autostart/deskmeter-task-window.desktop <<EOF
|
||||
[Desktop Entry]
|
||||
Type=Application
|
||||
Name=Deskmeter Task Window
|
||||
Exec=/home/mariano/wdir/dm/dmos/task_window.py
|
||||
Hidden=false
|
||||
NoDisplay=false
|
||||
X-GNOME-Autostart-enabled=true
|
||||
EOF
|
||||
```
|
||||
|
||||
### GNOME Extension
|
||||
|
||||
Enabled extensions auto-start with GNOME Shell. Just ensure it's enabled:
|
||||
```bash
|
||||
gnome-extensions enable deskmeter-indicator@local
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files Structure
|
||||
|
||||
```
|
||||
dmos/
|
||||
├── gnome-extension/
|
||||
│ ├── deskmeter-indicator@local/
|
||||
│ │ ├── extension.js # Main extension code
|
||||
│ │ ├── metadata.json # GNOME metadata
|
||||
│ │ ├── stylesheet.css # Panel styling
|
||||
│ │ └── deskmeter-indicator@local.zip # Packaged extension
|
||||
│ ├── install.sh # Initial installation
|
||||
│ └── update.sh # Update after changes
|
||||
└── task_window.py # GTK4 window app
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### GTK Window
|
||||
- [ ] Window appears without decorations
|
||||
- [ ] Shows current task path
|
||||
- [ ] Can be moved/positioned
|
||||
- [ ] Closes with Alt+F4
|
||||
- [ ] Updates on workspace change (~2s delay)
|
||||
- [ ] Can set always-on-top with wmctrl
|
||||
- [ ] Auto-detects port (check console)
|
||||
|
||||
### GNOME Extension
|
||||
- [ ] Shows in panel (left side)
|
||||
- [ ] Displays current task
|
||||
- [ ] Updates on workspace switch (~2s delay)
|
||||
- [ ] Doesn't crash GNOME Shell if dmweb offline
|
||||
- [ ] Can disable: `gnome-extensions disable deskmeter-indicator@local`
|
||||
- [ ] Truncates long paths correctly
|
||||
|
||||
---
|
||||
|
||||
## Performance
|
||||
|
||||
### GTK Window
|
||||
- Workspace checks: 200ms interval (lightweight wmctrl)
|
||||
- Task updates: 2000ms interval
|
||||
- Post-switch delay: 2200ms (allows dmcore to update)
|
||||
- CPU usage: ~0.1-0.2%
|
||||
|
||||
### GNOME Extension
|
||||
- Event-driven (workspace switches)
|
||||
- Periodic refresh: 30s
|
||||
- Debounce delay: 2200ms
|
||||
- Minimal overhead (GNOME Shell event loop)
|
||||
|
||||
---
|
||||
|
||||
## Development
|
||||
|
||||
### Updating Extension
|
||||
|
||||
```bash
|
||||
cd dmos/gnome-extension
|
||||
|
||||
# 1. Edit extension.js, metadata.json, or stylesheet.css
|
||||
|
||||
# 2. Update installed version
|
||||
./update.sh
|
||||
|
||||
# 3. Restart GNOME Shell
|
||||
# X11: Alt+F2 → 'r' → Enter
|
||||
# Wayland: Log out and back in
|
||||
|
||||
# 4. Check logs for errors
|
||||
journalctl -f -o cat /usr/bin/gnome-shell | grep deskmeter
|
||||
```
|
||||
|
||||
### Updating Window
|
||||
|
||||
```bash
|
||||
# 1. Edit dmos/task_window.py
|
||||
|
||||
# 2. Kill running instance
|
||||
pkill -f task_window.py
|
||||
|
||||
# 3. Run updated version
|
||||
python3 dmos/task_window.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Endpoint
|
||||
|
||||
Both components use the same endpoint:
|
||||
|
||||
**URL**: `http://localhost:{PORT}/api/current_task`
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"task_id": "abc12345",
|
||||
"task_path": "work/default"
|
||||
}
|
||||
```
|
||||
|
||||
**Error Handling**:
|
||||
- Connection refused → "offline"
|
||||
- Invalid JSON → "error"
|
||||
- Missing task_path → "no task"
|
||||
|
||||
---
|
||||
|
||||
## Need Help?
|
||||
|
||||
1. **Start with** [READY_TO_TEST.md](READY_TO_TEST.md) for immediate testing
|
||||
2. **For task window issues** see [TASK_WINDOW_README.md](TASK_WINDOW_README.md)
|
||||
3. **For extension issues** see [INSTALL_STATUS.md](INSTALL_STATUS.md)
|
||||
4. **For port problems** see [PORT_DETECTION_README.md](PORT_DETECTION_README.md)
|
||||
1. **Start dmweb**: `cd dmapp/dmweb && python3 run.py`
|
||||
2. **Test API**: `curl http://localhost:10000/api/current_task`
|
||||
3. **Try window first**: `python3 dmos/task_window.py` (no logout)
|
||||
4. **Check logs**: `journalctl` for extension, console for window
|
||||
5. **Verify ports**: `ss -tlnp | grep -E "(10000|10001)"`
|
||||
|
||||
---
|
||||
|
||||
**Ready to test!** Start with the GTK window for immediate feedback, then try the extension for permanent integration.
|
||||
|
||||
Reference in New Issue
Block a user