GridSnap/README.md

# 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
- **Graphical Zone Editor**: Draw custom zones visually with your mouse - no code editing required!
- **Visual Overlay**: See your zones while dragging windows (hold Shift)
- **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 + Shift + E**: Open graphical zone editor
- **Super + Ctrl + 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

### Graphical Zone Editor

Create custom layouts visually by drawing zones with your mouse:

1. Press **Super + Shift + E** to open the zone editor
2. **Click and drag** to draw rectangular zones
3. Draw as many zones as you need
4. **Ctrl + S** to save your custom layout
5. **Ctrl + C** or **Escape** to cancel
6. **Delete/Backspace** to remove the last zone

Your custom layout will be added to the layout rotation and can be accessed with Super + Shift + Z.

## 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

### Easy Way: Use the Graphical Editor

1. Press **Super + Shift + E** to open the zone editor
2. Draw zones by clicking and dragging
3. Press **Ctrl + S** to save your custom layout
4. Your layout is immediately available in the layout rotation!

### Advanced Way: Edit the Code

To add your own layouts manually, 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

- [x] Custom layout editor GUI
- [ ] Per-monitor zone configurations
- [ ] Save custom layouts permanently to file
- [ ] Edit existing custom layouts in the graphical editor
- [ ] Zone layout import/export
- [ ] More pre-configured layouts
- [ ] Animation effects
- [ ] Settings panel for keybinding customization

## 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.