Cursor rule

1---
2description: UI/UX patterns and window management guide
3globs: ["**/*.xaml", "**/*.xaml.cs"]
4alwaysApply: false
5---
6 
7# UI/UX Patterns and Window Management Guide
8 
9## Window Architecture
10 
11### Window Types
12UGTLive uses several specialized windows, each with specific responsibilities:
13 
141. **Main Window** ([src/MainWindow.xaml](mdc:src/MainWindow.xaml))
15   - Central control panel
16   - Start/Stop translation
17   - Access to all other windows
18   - System tray integration
19 
202. **Monitor Window** ([src/MonitorWindow.xaml](mdc:src/MonitorWindow.xaml))
21   - Live preview of capture area
22   - Visual OCR feedback
23   - Resizable and movable
24 
253. **ChatBox Window** ([src/ChatBoxWindow.xaml](mdc:src/ChatBoxWindow.xaml))
26   - Translation display overlay
27   - Always-on-top option
28   - Customizable appearance
29 
304. **Settings Window** ([src/SettingsWindow.xaml](mdc:src/SettingsWindow.xaml))
31   - Tabbed interface for all settings
32   - API key management
33   - Service configuration
34   - OCR and translation settings
35 
365. **Log Window** ([src/LogWindow.xaml](mdc:src/LogWindow.xaml))
37   - Application log viewer
38   - Real-time log updates
39   - Filtering and search
40 
41## Keyboard Shortcuts ([src/HotkeyManager.cs](mdc:src/HotkeyManager.cs))
42 
43### Global Shortcuts
44All shortcuts are managed through HotkeyManager and configurable via hotkeys.txt:
45 
46| Action | Default | Event |
47|--------|---------|-------|
48| Start/Stop OCR | Shift+S | `StartStopRequested` |
49| Show/Hide Monitor | Shift+M | `MonitorToggleRequested` |
50| Show/Hide ChatBox | Shift+C | `ChatBoxToggleRequested` |
51| Show/Hide Settings | Shift+P | `SettingsToggleRequested` |
52| Show/Hide Log | Shift+L | `LogToggleRequested` |
53| Show/Hide Main Window | Shift+H | `MainWindowVisibilityToggleRequested` |
54| Clear Overlays | Shift+X | `ClearOverlaysRequested` |
55| Passthrough Toggle | Shift+T | `PassthroughToggleRequested` |
56| Overlay Mode Toggle | Shift+O | `OverlayModeToggleRequested` |
57| Listen Toggle | Shift+A | `ListenToggleRequested` |
58| View in Browser | Shift+B | `ViewInBrowserRequested` |
59| Play All Audio | Shift+W | `PlayAllAudioRequested` |
60 
61### Implementation Pattern
62```csharp
63// Register hotkey events
64HotkeyManager.Instance.StartStopRequested += OnStartStopRequested;
65HotkeyManager.Instance.MonitorToggleRequested += OnMonitorToggleRequested;
66 
67// Hotkeys are loaded from hotkeys.txt and can be customized
68```
69 
70### Hotkey Configuration
71Hotkeys are stored in `hotkeys.txt` with format:
72```
73action=key1+key2+key3
74```
75 
76## UI Design Patterns
77 
78### Window Lifecycle
791. **Creation**: Windows created once at startup
802. **Visibility**: Show/Hide instead of Create/Destroy
813. **State Persistence**: Position and size saved via ConfigManager
824. **Cleanup**: Proper disposal on application exit
83 
84### Common Window Properties
85```xml
86<!-- Standard window attributes -->
87WindowStyle="None"
88AllowsTransparency="True"
89ResizeMode="CanResize"
90Topmost="{Binding IsAlwaysOnTop}"
91```
92 
93### Styling Conventions
94 
95#### Colors and Themes
96- Dark theme by default
97- Configurable accent colors
98- Semi-transparent backgrounds
99- High contrast text
100 
101#### Standard Controls
102```xml
103<!-- Button Style -->
104<Button Style="{StaticResource ModernButton}"
105        Background="#FF2D2D30"
106        Foreground="White"
107        BorderThickness="0"/>
108 
109<!-- TextBox Style -->
110<TextBox Style="{StaticResource ModernTextBox}"
111         Background="#FF3F3F46"
112         Foreground="White"
113         BorderBrush="#FF007ACC"/>
114```
115 
116## ChatBox Customization
117 
118### Appearance Settings ([src/ChatBoxOptionsWindow.xaml](mdc:src/ChatBoxOptionsWindow.xaml))
119- Background color picker
120- Text color picker
121- Transparency slider (0-100%)
122- Font family and size
123- Border options
124 
125### Layout Options
126- Auto-size to content
127- Maximum width/height
128- Text alignment
129- Padding configuration
130 
131## Settings Organization
132 
133### Tab Structure in Settings Window
1341. **General**: Basic app settings, hotkeys
1352. **OCR**: OCR service selection and config
1363. **Translation**: Service selection and API keys
1374. **ChatBox**: Display preferences
1385. **Audio**: TTS settings and voice selection
1396. **Advanced**: Debug and experimental features
140 
141### Settings Pattern
142```csharp
143// Property in ConfigManager
144public string GetSetting() => GetValue(SETTING_KEY, defaultValue);
145public void SetSetting(string value)
146{
147    SetValue(SETTING_KEY, value);
148    SaveConfig();
149}
150 
151// UI Binding in XAML
152<TextBox Text="{Binding SettingName, Mode=TwoWay}"/>
153```
154 
155## Mouse Interaction ([src/MouseManager.cs](mdc:src/MouseManager.cs))
156 
157### Region Selection
158- Click and drag to select area
159- Visual feedback during selection
160- Escape key to cancel
161- Double-click to confirm
162 
163### Window Dragging
164- Custom title bar implementation
165- Drag from any empty area
166- Snap to screen edges
167 
168## Notification Patterns
169 
170### Status Messages
171- Displayed in main window status bar
172- Auto-fade after 3 seconds
173- Color-coded by type (info, warning, error)
174 
175### Error Handling UI
176```csharp
177// Show error via ErrorPopupManager
178ErrorPopupManager.ShowError("Error Title", "Error message");
179 
180// Or show in UI
181Application.Current.Dispatcher.Invoke(() =>
182{
183    StatusText.Text = $"Error: {message}";
184    StatusText.Foreground = Brushes.Red;
185});
186```
187 
188## Accessibility Considerations
189 
190### Keyboard Navigation
191- Tab order properly set
192- All functions keyboard accessible
193- Tooltips for all controls
194- Keyboard shortcuts documented
195 
196### Visual Accessibility
197- High contrast mode support
198- Configurable font sizes
199- Color customization
200- Clear visual feedback
201 
202## Performance UI Guidelines
203 
204### Responsive Design
205- Async operations for long tasks
206- Progress indicators
207- Non-blocking UI updates
208- Smooth animations
209 
210### Update Patterns
211```csharp
212// UI updates from background thread
213Application.Current.Dispatcher.Invoke(() =>
214{
215    // Update UI elements
216}, DispatcherPriority.Background);
217```
218 
219## Window State Management
220 
221### Saving Window State
222```csharp
223// On window closing
224ConfigManager.Instance.SetWindowPosition(
225    windowName, this.Left, this.Top, 
226    this.Width, this.Height);
227 
228// On window loading
229var pos = ConfigManager.Instance.GetWindowPosition(windowName);
230if (pos != null)
231{
232    this.Left = pos.X;
233    this.Top = pos.Y;
234    this.Width = pos.Width;
235    this.Height = pos.Height;
236}
237```
238 
239### Multi-Monitor Support
240- Remember which monitor
241- Handle monitor disconnection
242- Validate window positions
243- Prevent off-screen windows
244 
245## Custom Controls
246 
247### Draggable Thumb Control
248Used for resizing regions and windows:
249```xml
250<Thumb DragDelta="Thumb_DragDelta"
251       Width="10" Height="10"
252       Cursor="SizeNWSE"/>
253```
254 
255### Color Picker Integration
256- Uses standard WPF color dialog
257- Preview of selected color
258- Saves recent colors
259- Hex value display
260 
261## Animation Guidelines
262 
263### Fade Animations
264```xml
265<Storyboard x:Key="FadeIn">
266    <DoubleAnimation 
267        Storyboard.TargetProperty="Opacity"
268        From="0" To="1" Duration="0:0:0.3"/>
269</Storyboard>
270```
271 
272### Smooth Transitions
273- 300ms standard duration
274- Ease-in-out timing function
275- Avoid jarring movements
276- Respect reduced motion preference
277 
278## Service Management UI
279 
280### Service Installation Dialog
281- Shows available Python OCR services
282- Installation progress
283- Error handling and diagnostics
284 
285### Service Diagnostics
286- Health check status
287- Port availability
288- Service logs
289- Test image processing
290 
291## Dialog Patterns
292 
293### Modal Dialogs
294```csharp
295var dialog = new SettingsWindow();
296dialog.Owner = this;
297dialog.ShowDialog(); // Blocks until closed
298```
299 
300### Confirmation Dialogs
301```csharp
302var result = MessageBox.Show(
303    "Are you sure you want to delete this?",
304    "Confirm",
305    MessageBoxButton.YesNo,
306    MessageBoxImage.Question);
307 
308if (result == MessageBoxResult.Yes)
309{
310    // Perform action
311}
312```
313