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:

   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:

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:

global.log('GridSnap: Your message here');

View logs with:

tail -f ~/.cinnamon/glass.log

Future Enhancements

• Custom layout editor GUI
• Per-monitor zone configurations
• Save custom layouts permanently to file
• Edit existing custom layouts in the graphical editor
• Animation effects
• 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.