GridSnap/README.md

# GridSnap for Cinnamon Desktop

A window tiling manager extension for Linux Mint's Cinnamon Desktop, inspired by Microsoft PowerToys FancyZones.

## Features

- **Split-Based Zone Editor**: Create layouts by splitting zones horizontally or vertically - intuitive tiling interface!
- **Multi-Monitor Support**: Independent zone configurations for each monitor
- **Multiple Zone Layouts**: Pre-configured layouts including 2x2 grid, 3 columns, and focus layouts
- **Real-Time Dimensions**: See pixel and percentage dimensions in each zone
- **Visual Overlay**: See your zones while dragging windows (hold Shift)
- **Keyboard Shortcuts**: Quick snap to zones using hotkeys
- **Persistent Storage**: Custom layouts saved per-monitor with automatic migration

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

**Global Shortcuts:**
- **Super + Z**: Toggle zone overlay (show/hide zones)
- **Super + Shift + Z**: Cycle through different layouts
- **Super + Shift + E**: Open zone editor
- **Super + Ctrl + 1-9**: Snap focused window to zone 1-9

**Zone Editor Shortcuts:**
- **H**: Split selected zone horizontally (creates top/bottom)
- **V**: Split selected zone vertically (creates left/right)
- **Delete**: Remove selected zone
- **Ctrl + S**: Save layout
- **Escape**: Cancel and close editor

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

### Split-Based Zone Editor

Create custom layouts by progressively splitting zones:

1. Press **Super + Shift + E** to open the zone editor
2. Select which monitor to edit (if you have multiple monitors)
3. Choose to create a new layout or edit an existing one
4. Editor starts with **one full-screen zone** (highlighted in yellow)
5. **Click** a zone to select it
6. Press **H** to split horizontally (top/bottom) or **V** to split vertically (left/right)
7. **Drag dividers** between zones to adjust their positions
8. Press **Delete** to remove the selected zone
9. **Ctrl + S** to save your custom layout
10. **Escape** to cancel

Each zone displays its dimensions in pixels and percentages in real-time. Your custom layout will be saved per-monitor 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 Split-Based Editor

1. Press **Super + Shift + E** to open the zone editor
2. Select your monitor (if you have multiple)
3. Split zones using **H** (horizontal) and **V** (vertical)
4. Adjust dividers by dragging them
5. Press **Ctrl + S** to save your custom layout
6. Your layout is immediately available and saved per-monitor!

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

## Multi-Monitor Support

GridSnap fully supports multiple monitors with independent configurations:

- **Per-Monitor Layouts**: Each monitor can have its own set of custom layouts
- **Monitor Selector**: Choose which monitor to edit when opening the zone editor
- **Automatic Detection**: Window snapping automatically uses the correct monitor's zones
- **Keyboard Shortcuts**: Work on any monitor - snaps to zones on the monitor where the window is located
- **Settings Panel**: Manage layouts per-monitor with a dropdown selector
- **Storage Migration**: Existing layouts automatically migrate to the primary monitor

When you open the zone editor, you'll be prompted to select which monitor to configure. Each monitor maintains its own:
- Current active layout
- Custom layouts
- Zone configurations

## 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
- [x] Per-monitor zone configurations
- [x] Save custom layouts permanently to file
- [x] Edit existing custom layouts in the graphical editor
- [x] Animation effects
- [x] Settings panel (zone appearance, toggles, layout management)
- [ ] Zone layout import/export
- [ ] More pre-configured layouts
- [ ] High-DPI display support
- [ ] Keybinding customization in settings panel

## Contributing

Feel free to fork and submit pull requests! Areas that could use help:
- Additional layout presets
- High-DPI display support and testing
- Zone layout import/export functionality
- UI improvements and animations
- Performance optimizations

## License

MIT License - Feel free to use and modify as needed.

## Credits

Inspired by Microsoft PowerToys FancyZones for Windows.