deskmeter/docs/TASK_WINDOW_README.md

Deskmeter Task Window - Regular Mode

A simple GTK4 window that displays your current deskmeter task, with always-on-top and sticky (visible on all workspaces) properties.

Why Use This?

• Testing: Test the dmweb API integration without needing to restart GNOME Shell
• Temporary solution: Use while waiting to log out/in to activate the extension
• Standalone mode: If you prefer a window instead of a panel indicator

Prerequisites

• Python 3 with GTK4 bindings (python3-gi)
• dmweb server running on http://localhost:10000
• wmctrl installed (for always-on-top functionality)

Quick Start

Option 1: Using the launcher script (recommended)

cd /home/mariano/wdir/dm-gnomeext
./run_task_window.sh

This will:

1. Start the task window
2. Automatically set it to always-on-top
3. Make it visible on all workspaces (sticky)

Option 2: Run Python script directly

cd /home/mariano/wdir/dm-gnomeext
python3 task_window.py

Then manually set window properties:

• Right-click window title bar → "Always on Top"
• Right-click window title bar → "Always on Visible Workspace" (if available)

Or use wmctrl:

# After window appears
wmctrl -r "Deskmeter Task" -b add,above,sticky

What You'll See

• Loading... - Initial state while fetching first task
• work/default - Your current task path (updates every 2.2 seconds)
• offline - dmweb not running (red) - Cannot connect to API
• error - invalid API response (orange) - API returned invalid JSON
• no task - Valid response but no current task set

Configuration

Edit task_window.py to customize:

UPDATE_INTERVAL = 2200  # Update frequency in milliseconds
DESKMETER_API_URL = 'http://localhost:10000/api/current_task'  # API endpoint

Window appearance (line ~24):

self.set_default_size(400, 80)  # Width x Height

Font size and styling (line ~27):

self.label.set_markup('<span font_desc="14">Loading...</span>')

Stopping the Window

• Close the window normally (X button)
• Or kill the process: pkill -f task_window.py

Troubleshooting

"offline - dmweb not running"

Start the dmweb server:

cd ~/path/to/dm/dmapp/dmweb
python3 run.py

Test manually:

curl http://localhost:10000/api/current_task

Window not staying on top

# Manually set properties
wmctrl -r "Deskmeter Task" -b add,above,sticky

# Check if wmctrl is installed
which wmctrl
# If not: sudo apt install wmctrl

GTK4 not found

# Install GTK4 Python bindings
sudo apt install python3-gi gir1.2-gtk-4.0

Window appears on wrong workspace

Use wmctrl to make it sticky (visible on all workspaces):

wmctrl -r "Deskmeter Task" -b add,sticky

Comparison: Window vs Extension

Feature	Task Window (this)	GNOME Extension
Always visible	✅ (when on top)	✅ (in panel)
All workspaces	✅ (sticky)	✅ (panel always visible)
Screen space	Takes window space	No extra space
Setup	Run anytime	Requires logout/login
Integration	Separate window	Native panel integration
Restart needed	No	Yes (on Wayland)

Usage Tips

1. Position: Drag to top-right corner of screen for minimal interference
2. Size: The window can be resized - smaller is less intrusive
3. Transparency: You can use GNOME Tweaks to make unfocused windows transparent
4. Auto-start: Add to Startup Applications if you want it to run on login

Adding to Startup (Optional)

# Create desktop entry
cat > ~/.config/autostart/deskmeter-task-window.desktop <<EOF
[Desktop Entry]
Type=Application
Name=Deskmeter Task Window
Exec=/home/mariano/wdir/dm-gnomeext/run_task_window.sh
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true
EOF

Files

• task_window.py - Main GTK4 Python application
• run_task_window.sh - Launcher script with wmctrl integration
• TASK_WINDOW_README.md - This file

Next Steps

Once you've tested that the API integration works with this window, you can log out/in to test the GNOME extension, which will provide the same information in the panel without taking up window space.