rmtPocketWatcher/flutter_app/WINDOW_MANAGEMENT_GUIDE.md

Window Management & System Tray Guide

Your rmtPocketWatcher application now includes comprehensive window management and system tray functionality for a professional desktop experience.

🪟 Window Controls

Title Bar Features

• Draggable Area: Click and drag anywhere on the title bar to move the window
• Double-click: Double-click the title bar to maximize/restore the window
• Custom Controls: Professional-looking minimize, maximize, and close buttons

Window Control Buttons

Button	Icon	Function	Tooltip
Minimize	−	Minimizes to system tray	"Minimize to system tray"
Maximize	⛶/⧉	Toggle maximize/restore	"Maximize window" / "Restore window"
Close	×	Closes to system tray	"Close to system tray"

Key Behaviors

• Close button minimizes to tray instead of exiting the application
• Minimize button sends the window directly to the system tray
• Window dragging works from anywhere on the title bar
• Maximize toggle remembers window state

🔔 System Tray Integration

Tray Icon Features

• Dynamic Tooltip: Shows current connection status
• Single Click: Toggle window visibility (show/hide)
• Right Click: Opens context menu with options
• Visual Indicator: Icon represents the application state

System Tray Menu

Menu Item	Function
Show rmtPocketWatcher	Restores window from tray
Check for Updates	Shows window and triggers update check
🔄 Update Available!	Appears when updates are detected
About	Shows application information dialog
Exit	Completely closes the application

Dynamic Status Updates

• Tooltip Updates: Reflects connection status ("Connected", "Disconnecting", etc.)
• Menu Updates: Shows update availability in real-time
• Status Integration: Syncs with price provider and update provider

🎛️ User Experience

Window Lifecycle

1. Startup: Window appears normally
2. Minimize: Window hides to system tray
3. Tray Click: Window restores and focuses
4. Close: Window hides to tray (doesn't exit)
5. Exit: Only via tray menu "Exit" option

Professional Features

• No Taskbar Clutter: Minimized windows don't show in taskbar
• Background Operation: App continues running when minimized
• Quick Access: Single click to restore from tray
• Status Awareness: Tray shows current application state

🔧 Technical Implementation

Core Components

WindowService (lib/services/window_service.dart)

• Manages all window operations
• Handles system tray integration
• Provides event listeners for window and tray events
• Integrates with application providers

Key Methods

WindowService().minimizeToTray()     // Hide to system tray
WindowService().showWindow()        // Restore from tray
WindowService().maximizeWindow()    // Toggle maximize state
WindowService().closeWindow()       // Close to tray
WindowService().exitApp()           // Complete application exit

Provider Integration

• PriceProvider: Updates tray tooltip with connection status
• UpdateProvider: Updates tray menu with update availability
• Real-time Sync: Tray reflects current application state

Event Handling

Window Events

• onWindowClose(): Intercepts close and minimizes to tray
• onWindowMinimize(): Handles minimize operations
• onWindowRestore(): Manages window restoration
• onWindowMaximize()/onWindowUnmaximize(): Toggle states

Tray Events

• onTrayIconMouseDown(): Single click to toggle visibility
• onTrayIconRightMouseDown(): Right click for context menu
• onTrayMenuItemClick(): Handle menu item selections

🎨 Visual Design

Title Bar Styling

• Background: Dark theme (#1A1F3A)
• Text: White application name and organization
• Buttons: Consistent with application theme
• Height: 40px for comfortable interaction

System Tray

• Icon: Application logo (falls back to analytics icon)
• Tooltip: Dynamic status information
• Menu: Consistent with application theme

🚀 Usage Examples

For End Users

Basic Window Management

• Drag title bar to move window
• Double-click title bar to maximize
• Click minimize (−) to hide to tray
• Click close (×) to hide to tray
• Right-click tray icon for menu
• Click "Exit" in tray menu to quit

System Tray Operations

• Single-click tray icon: Show/hide window
• Right-click tray icon: Open context menu
• Menu → "Show rmtPocketWatcher": Restore window
• Menu → "Check for Updates": Check for new versions
• Menu → "About": View application information
• Menu → "Exit": Completely close application

For Developers

Integrating with Providers

// Update tray status based on connection
WindowService().updateTrayTooltip('Connected to servers');

// Update menu with update availability
WindowService().updateTrayMenu(hasUpdate: true);

// Show about dialog from tray
WindowService()._showAboutDialog();

🔒 Security & Privacy

Safe Operations

• No Data Collection: Window management doesn't collect user data
• Local Storage: All preferences stored locally
• Secure Minimize: Sensitive data hidden when minimized
• Clean Exit: Proper cleanup on application exit

User Control

• Explicit Actions: All operations require user interaction
• Clear Feedback: Visual and tooltip feedback for all actions
• Reversible: All window states can be restored
• Transparent: Clear indication of application status

🛠️ Troubleshooting

Common Issues

System Tray Icon Not Appearing

• Cause: System tray initialization failed
• Solution: Check Windows notification area settings
• Workaround: Use window controls instead of tray

Window Won't Restore

• Cause: Window service not initialized
• Solution: Restart application
• Debug: Check console for initialization errors

Tray Menu Not Working

• Cause: Context menu creation failed
• Solution: Update tray manager package
• Workaround: Use window controls

Debug Information

// Check window service status
print('Window service initialized: ${WindowService().isInitialized}');
print('Minimized to tray: ${WindowService().isMinimizedToTray}');

📈 Future Enhancements

Planned Features

• Tray Notifications: Show price alerts in tray
• Quick Actions: Direct price check from tray menu
• Status Icons: Different icons for different connection states
• Keyboard Shortcuts: Global hotkeys for window operations

Customization Options

• Tray Behavior: Option to minimize to taskbar instead
• Close Behavior: Option to exit instead of minimize
• Startup Options: Start minimized to tray
• Theme Integration: Tray menu theme matching

📋 Summary

Your rmtPocketWatcher application now provides:

✅ Professional Window Management

• Draggable title bar with custom controls
• Proper minimize, maximize, and close operations
• Seamless window state management

✅ Complete System Tray Integration

• Hide to tray instead of taskbar clutter
• Dynamic status updates in tooltip
• Full-featured context menu

✅ User-Friendly Experience

• Intuitive window operations
• Clear visual feedback
• Professional desktop application behavior

✅ Developer-Friendly Architecture

• Clean service-based implementation
• Provider integration for real-time updates
• Extensible for future enhancements

The application now behaves like a professional desktop application with proper window management and system tray integration, providing users with a seamless and intuitive experience for monitoring AUEC prices.