Initial commit - GridSnap Cinnamon Extension

2026-01-16 01:34:29 +00:00
commit 51b7de23fa
7 changed files with 529 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,132 @@
+# GridSnap for Cinnamon Desktop
+
+A window tiling manager extension for Linux Mint's Cinnamon Desktop, inspired by Microsoft PowerToys FancyZones.
+
+## Features
+
+- **Multiple Zone Layouts**: Pre-configured layouts including 2x2 grid, 3 columns, and focus layouts
+- **Visual Overlay**: See your zones while dragging windows
+- **Keyboard Shortcuts**: Quick snap to zones using hotkeys
+- **Layout Cycling**: Switch between different zone layouts on the fly
+
+## Installation
+
+1. Copy the extension folder to your Cinnamon extensions directory:
+   ```bash
+   cp -r gridsnap-cinnamon ~/.local/share/cinnamon/extensions/gridsnap@cinnamon-extension
+   ```
+
+2. Restart Cinnamon (Alt+F2, type 'r', press Enter) or log out and back in
+
+3. Enable the extension:
+   - Open System Settings → Extensions
+   - Find "GridSnap"
+   - Toggle it on
+
+## Usage
+
+### Keyboard Shortcuts
+
+- **Super + Z**: Toggle zone overlay (show/hide zones)
+- **Super + Shift + Z**: Cycle through different layouts
+- **Super + Numpad 1-9**: Snap focused window to zone 1-9
+
+### Mouse Usage
+
+1. Hold **Shift** while dragging a window to see the zone overlay
+2. Drop the window over a zone to snap it there
+3. Release Shift or move outside zones to cancel
+
+## Available Layouts
+
+1. **2x2 Grid**: Four equal quadrants
+2. **3 Columns**: Three equal vertical columns
+3. **Focus Left**: Large left area with two smaller right zones
+
+## Customization
+
+To add your own layouts, edit the `DEFAULT_LAYOUTS` object in `extension.js`:
+
+```javascript
+const DEFAULT_LAYOUTS = {
+    'custom-layout': {
+        name: 'My Custom Layout',
+        zones: [
+            { x: 0, y: 0, width: 0.5, height: 1 },    // Left half
+            { x: 0.5, y: 0, width: 0.5, height: 1 }   // Right half
+        ]
+    }
+};
+```
+
+Zone coordinates are relative (0.0 to 1.0):
+- `x`: Horizontal position (0 = left edge, 1 = right edge)
+- `y`: Vertical position (0 = top edge, 1 = bottom edge)
+- `width`: Zone width as fraction of screen width
+- `height`: Zone height as fraction of screen height
+
+## Troubleshooting
+
+### Extension won't load
+- Check the Looking Glass console (Alt+F2, type 'lg', press Enter) for errors
+- Ensure the UUID in metadata.json matches the folder name
+
+### Overlay doesn't show
+- Make sure no other extensions conflict with window management
+- Try disabling and re-enabling the extension
+
+### Keybindings don't work
+- Check System Settings → Keyboard → Shortcuts for conflicts
+- Ensure the extension is enabled
+
+## Development
+
+### File Structure
+```
+gridsnap@cinnamon-extension/
+├── metadata.json       # Extension metadata
+├── extension.js        # Main extension code
+├── stylesheet.css      # Visual styling
+└── README.md          # This file
+```
+
+### Testing Changes
+After editing:
+1. Reload Cinnamon: Alt+F2 → 'r' → Enter
+2. Or use Looking Glass: Alt+F2 → 'lg' → Enter
+
+### Debug Logging
+Add logging in extension.js:
+```javascript
+global.log('GridSnap: Your message here');
+```
+View logs with:
+```bash
+tail -f ~/.cinnamon/glass.log
+```
+
+## Future Enhancements
+
+- [ ] Custom layout editor GUI
+- [ ] Per-monitor zone configurations
+- [ ] Save window positions and restore on login
+- [ ] Zone layout import/export
+- [ ] More pre-configured layouts
+- [ ] Animation effects
+- [ ] Settings panel for configuration
+
+## Contributing
+
+Feel free to fork and submit pull requests! Areas that could use help:
+- Additional layout presets
+- UI improvements for the overlay
+- Settings GUI implementation
+- Multi-monitor support improvements
+
+## License
+
+MIT License - Feel free to use and modify as needed.
+
+## Credits
+
+Inspired by Microsoft PowerToys FancyZones for Windows.