diff options
Diffstat (limited to 'docs/GUI_SETTINGS.md')
| -rw-r--r-- | docs/GUI_SETTINGS.md | 382 |
1 files changed, 382 insertions, 0 deletions
diff --git a/docs/GUI_SETTINGS.md b/docs/GUI_SETTINGS.md new file mode 100644 index 0000000..bc892b5 --- /dev/null +++ b/docs/GUI_SETTINGS.md @@ -0,0 +1,382 @@ +# SRDWM GUI Settings Program + +## Overview +The SRDWM GUI Settings program provides a user-friendly interface for configuring the window manager without editing Lua files directly. It integrates seamlessly with existing system settings structures on Windows, macOS, and Linux. + +## Architecture + +### Cross-Platform GUI Framework +- **Linux**: GTK4 with native desktop integration +- **Windows**: WinUI 3 with Windows Settings integration +- **macOS**: SwiftUI with System Preferences integration + +### System Integration +- **Windows**: Appears in Windows Settings > System > Window Manager +- **macOS**: Appears in System Preferences > Desktop & Screen Saver > Window Manager +- **Linux**: Appears in GNOME Settings, KDE System Settings, etc. + +## Main Interface + +### 1. General Settings Tab +``` +┌─────────────────────────────────────────────────────────┐ +│ General Settings │ +├─────────────────────────────────────────────────────────┤ +│ Default Layout: [Dynamic ▼] │ +│ Smart Window Placement: ☑ │ +│ Window Gap: [8] pixels │ +│ Border Width: [2] pixels │ +│ Enable Animations: ☑ │ +│ Animation Duration: [200] ms │ +│ │ +│ Focus Follows Mouse: ☐ │ +│ Mouse Follows Focus: ☑ │ +│ Auto Raise Windows: ☐ │ +│ Auto Focus Windows: ☑ │ +└─────────────────────────────────────────────────────────┘ +``` + +### 2. Key Bindings Tab +``` +┌─────────────────────────────────────────────────────────┐ +│ Key Bindings │ +├─────────────────────────────────────────────────────────┤ +│ Layout Switching │ +│ ├─ Tiling Layout: [Mod4+1] [Change] [Remove] │ +│ ├─ Dynamic Layout: [Mod4+2] [Change] [Remove] │ +│ └─ Floating Layout: [Mod4+3] [Change] [Remove] │ +│ │ +│ Window Management │ +│ ├─ Close Window: [Mod4+q] [Change] [Remove] │ +│ ├─ Minimize Window: [Mod4+m] [Change] [Remove] │ +│ └─ Maximize Window: [Mod4+f] [Change] [Remove] │ +│ │ +│ [Add New Binding] │ +└─────────────────────────────────────────────────────────┘ +``` + +### 3. Layouts Tab +``` +┌─────────────────────────────────────────────────────────┐ +│ Layouts │ +├─────────────────────────────────────────────────────────┤ +│ Tiling Layout │ +│ ├─ Split Ratio: [50]% [Reset] │ +│ ├─ Master Ratio: [60]% [Reset] │ +│ ├─ Auto Swap: ☑ │ +│ └─ Gaps: Inner [8] Outer [16] [Reset] │ +│ │ +│ Dynamic Layout │ +│ ├─ Snap Threshold: [50]px [Reset] │ +│ ├─ Grid Size: [6] [Reset] │ +│ ├─ Cascade Offset: [30]px [Reset] │ +│ └─ Smart Placement: ☑ │ +│ │ +│ [Add Custom Layout] │ +└─────────────────────────────────────────────────────────┘ +``` + +### 4. Themes Tab +``` +┌─────────────────────────────────────────────────────────┐ +│ Themes │ +├─────────────────────────────────────────────────────────┤ +│ Current Theme: [Nord ▼] [Preview] │ +│ │ +│ Colors │ +│ ├─ Background: [■] #2e3440 [Change] │ +│ ├─ Foreground: [■] #eceff4 [Change] │ +│ ├─ Primary: [■] #88c0d0 [Change] │ +│ └─ Secondary: [■] #81a1c1 [Change] │ +│ │ +│ Window Decorations │ +│ ├─ Border Width: [2]px [Reset] │ +│ ├─ Title Bar Height: [24]px [Reset] │ +│ └─ Font: [JetBrains Mono 10] [Change] │ +│ │ +│ [Import Theme] [Export Theme] [Create New] │ +└─────────────────────────────────────────────────────────┘ +``` + +### 5. Window Rules Tab +``` +┌─────────────────────────────────────────────────────────┐ +│ Window Rules │ +├─────────────────────────────────────────────────────────┤ +│ Rule 1: Firefox → Dynamic Layout │ +│ ├─ Match: Class = "firefox" │ +│ ├─ Action: Layout = "dynamic" │ +│ └─ [Edit] [Delete] │ +│ │ +│ Rule 2: Terminal → Tiling Layout │ +│ ├─ Match: Class = "terminal" │ +│ ├─ Action: Layout = "tiling" │ +│ └─ [Edit] [Delete] │ +│ │ +│ [Add New Rule] │ +└─────────────────────────────────────────────────────────┘ +``` + +### 6. Performance Tab +``` +┌─────────────────────────────────────────────────────────┐ +│ Performance │ +├─────────────────────────────────────────────────────────┤ +│ Graphics │ +│ ├─ Enable V-Sync: ☑ │ +│ ├─ Max FPS: [60] [Reset] │ +│ └─ Enable Caching: ☑ │ +│ │ +│ Memory │ +│ ├─ Window Cache Size: [100] [Reset] │ +│ ├─ Event Queue Size: [1000] [Reset] │ +│ └─ Layout Timeout: [16]ms [Reset] │ +│ │ +│ [Optimize for Performance] [Reset to Defaults] │ +└─────────────────────────────────────────────────────────┘ +``` + +## Key Binding Editor + +### Add/Edit Key Binding Dialog +``` +┌─────────────────────────────────────────────────────────┐ +│ Edit Key Binding │ +├─────────────────────────────────────────────────────────┤ +│ Key Combination: [Press keys here...] │ +│ Current: Mod4+Shift+1 │ +│ │ +│ Action Type: [Window Management ▼] │ +│ Action: [Close Window ▼] │ +│ │ +│ Custom Command: [________________] │ +│ │ +│ [Test Binding] [OK] [Cancel] │ +└─────────────────────────────────────────────────────────┘ +``` + +### Key Combination Parser +- **Mod4**: Super/Windows key +- **Mod1**: Alt key +- **Mod2**: Num Lock +- **Mod3**: Scroll Lock +- **Shift**: Shift key +- **Ctrl**: Control key + +## Theme Editor + +### Color Picker Integration +``` +┌─────────────────────────────────────────────────────────┐ +│ Color Picker │ +├─────────────────────────────────────────────────────────┤ +│ Color: [■] #88c0d0 │ +│ │ +│ RGB: R [136] G [192] B [208] │ +│ HSV: H [199] S [35] V [82] │ +│ │ +│ Preset Colors: │ +│ [■][■][■][■][■][■][■][■] │ +│ │ +│ [Pick from Screen] [OK] [Cancel] │ +└─────────────────────────────────────────────────────────┘ +``` + +### Font Selector +``` +┌─────────────────────────────────────────────────────────┐ +│ Font Selection │ +├─────────────────────────────────────────────────────────┤ +│ Font Family: [JetBrains Mono ▼] │ +│ Font Size: [10] [Reset] │ +│ Font Weight: [Normal ▼] │ +│ Font Style: [Normal ▼] │ +│ │ +│ Preview: The quick brown fox jumps over the lazy dog │ +│ │ +│ [OK] [Cancel] │ +└─────────────────────────────────────────────────────────┘ +``` + +## System Integration + +### Windows Integration +```cpp +// Windows Settings integration +class WindowsSettingsIntegration { +public: + void register_with_settings(); + void create_settings_page(); + void handle_settings_changes(); + +private: + void add_to_windows_settings(); + void create_registry_entries(); + void register_protocol_handler(); +}; +``` + +### macOS Integration +```swift +// macOS System Preferences integration +class MacOSSettingsIntegration: NSObject { + func registerWithSystemPreferences() + func createPreferencesPane() + func handlePreferencesChanges() + + private func addToSystemPreferences() + func createPreferencePaneBundle() + func registerURLScheme() +} +``` + +### Linux Integration +```cpp +// Linux desktop integration +class LinuxDesktopIntegration { +public: + void register_with_desktop(); + void create_settings_app(); + void handle_settings_changes(); + +private: + void add_to_gnome_settings(); + void add_to_kde_settings(); + void create_desktop_file(); + void register_mime_types(); +}; +``` + +## Configuration Management + +### Auto-Save and Validation +```cpp +class ConfigurationManager { +public: + void auto_save_changes(); + bool validate_configuration(); + void backup_configuration(); + void restore_configuration(); + +private: + void save_to_lua_files(); + void validate_lua_syntax(); + void create_backup(); + void notify_user_of_changes(); +}; +``` + +### Import/Export +```cpp +class ConfigurationIO { +public: + bool import_configuration(const std::string& path); + bool export_configuration(const std::string& path); + bool import_from_other_wm(const std::string& wm_name); + +private: + void parse_import_format(); + void convert_to_srdwm_format(); + void validate_imported_config(); +}; +``` + +## Advanced Features + +### Live Preview +- **Real-time updates**: Changes apply immediately +- **Window preview**: See how windows will look +- **Layout preview**: Visualize layout changes +- **Theme preview**: Live theme switching + +### Configuration Sync +- **Cloud sync**: Sync settings across devices +- **Version control**: Track configuration changes +- **Backup/restore**: Automatic configuration backups +- **Migration tools**: Import from other window managers + +### Accessibility +- **High contrast**: High contrast mode support +- **Screen reader**: Full screen reader compatibility +- **Keyboard navigation**: Complete keyboard navigation +- **Large text**: Scalable interface elements + +## Installation and Distribution + +### Package Integration +```bash +# Linux (Debian/Ubuntu) +sudo apt install srdwm-settings + +# Linux (Arch) +sudo pacman -S srdwm-settings + +# Windows (Chocolatey) +choco install srdwm-settings + +# macOS (Homebrew) +brew install srdwm-settings +``` + +### System Integration +```bash +# Linux desktop files +~/.local/share/applications/srdwm-settings.desktop + +# Windows registry +HKEY_CURRENT_USER\Software\SRDWM\Settings + +# macOS preferences +~/Library/Preferences/com.srdwm.settings.plist +``` + +## Development + +### Building the GUI +```bash +# Linux (GTK4) +meson build -Dgui=true +ninja -C build + +# Windows (WinUI 3) +dotnet build src/gui/SRDWM.Settings.Windows + +# macOS (SwiftUI) +xcodebuild -project src/gui/SRDWM.Settings.macOS.xcodeproj +``` + +### Testing +```bash +# Unit tests +ninja -C build test + +# Integration tests +ninja -C build integration-test + +# GUI tests +ninja -C build gui-test +``` + +## User Experience + +### First Run Experience +1. **Welcome dialog**: Introduction to SRDWM +2. **Quick setup**: Essential settings configuration +3. **Tutorial**: Interactive configuration guide +4. **Import options**: Import from existing setups + +### Contextual Help +- **Tooltips**: Hover for help text +- **Help button**: Context-sensitive help +- **Documentation**: Integrated user manual +- **Examples**: Sample configurations + +### Error Handling +- **Validation**: Real-time configuration validation +- **Error messages**: Clear, actionable error messages +- **Recovery**: Automatic error recovery +- **Logging**: Detailed error logging + +This GUI settings program provides a professional, user-friendly interface that integrates seamlessly with existing system structures while maintaining the power and flexibility of the Lua configuration system. + + |