How Widget Edit Mode and Snap-to-Grid Work

Atmos widgets look simple on the surface, but the interaction model behind them is more carefully designed than it first appears.

There is an edit mode, a separate overlay system, live drag and resize feedback, tap-to-open widget options, and an optional snap-to-grid layout mode that changes how final placement is stored.

This guide explains how those pieces work together and what hidden behaviors matter when you are arranging widgets on your desktop.

Widget editing only happens in edit mode

Atmos does not treat desktop widgets as always-editable floating objects.

Instead, widget manipulation is gated behind a dedicated edit mode. That matters because it keeps ordinary desktop use from constantly turning into accidental widget movement.

In normal operation, widgets are meant to sit quietly on the desktop.

In edit mode, Atmos turns the widget layer into something you can actively rearrange.

The widget overlay is visual, not click-capturing

One of the most important hidden details is that the widget overlay window does not intercept mouse events directly.

The overlay is displayed at desktop level and is configured to ignore mouse events. Atmos then uses event monitoring to interpret clicks, drags, and releases separately.

That design helps widgets behave like part of the desktop without becoming a fragile normal app window sitting on top of everything else.

Hidden behavior: Atmos uses event monitors instead of ordinary SwiftUI gestures

Widget interaction is not driven by regular SwiftUI drag gestures on the widget views.

Instead, Atmos listens for:

• global mouse down, drag, and up events
• local mouse down, drag, and up events

This allows widget editing to work even when the Finder or another app is active, as long as the interaction is happening on the desktop widget layer.

That is a big part of why the widget system feels more native to the desktop than a normal in-app canvas.

Entering edit mode unlocks widget interaction

When edit mode turns on, Atmos begins interpreting widget interactions as editable operations.

That includes:

• selecting a widget
• dragging a widget
• resizing a widget
• deleting a widget

When edit mode turns off, live drag and resize state is cleared and the current widget layout is saved.

Hidden behavior: leaving edit mode clears live interaction state

Atmos does not let temporary drag and resize visuals linger after edit mode ends.

If you leave edit mode, the engine clears:

• the live drag target
• the live drag offset
• the live resize target
• the temporary resize delta
• the current interaction mode

This keeps the overlay from getting stuck in a half-edited visual state.

Widgets get visual edit chrome in edit mode

When edit mode is active, widgets show extra visual controls on top of their normal content.

That chrome includes:

• a delete control in the top-right area
• a resize handle in the bottom-right area
• an outline around the widget

These are not regular buttons in the normal sense. They are visual markers that help Atmos interpret where the click happened.

Hidden behavior: delete and resize are corner zones

Atmos decides what action to take by checking where your click landed relative to the widget frame.

It uses small corner hit zones for:

• delete
• resize

If the click lands outside those zones but still inside the widget frame, Atmos treats it as a body interaction.

That means the widget surface has distinct interaction meanings even though the overlay itself is not directly handling SwiftUI button clicks.

Tapping a widget opens its options panel

In edit mode, a small tap on a widget body does not move it. Instead, it selects that widget and opens the widget options panel in the Atmos window.

This is how users get to widget-specific settings like:

• style
• opacity
• font choices
• color mode
• widget-specific options

That tap behavior is a big part of the editing flow.

Hidden behavior: tapping the same widget again closes its panel

Atmos treats widget selection as toggleable.

If you tap a widget that is already selected, the options panel closes instead of selecting it again redundantly.

That small toggle behavior makes the editing flow feel cleaner and less sticky.

Atmos distinguishes taps from drags by movement distance

Another important hidden detail is that Atmos uses drag distance to decide whether your interaction was really a tap or a movement.

If the pointer barely moves, the action is treated like a click.

If it moves beyond a small threshold, Atmos switches into live drag or live resize behavior instead.

This helps the system avoid confusing a short tap with a full reposition.

Dragging shows live movement before the final position is saved

When you drag a widget, Atmos first updates the widget visually using a live offset.

That means the widget appears to move immediately as you drag, but the stored position is not committed until mouse-up.

This separation gives the drag interaction a smoother feel and keeps the saved state from being rewritten every frame during the motion.

Resizing works similarly

Resize behavior follows the same general pattern.

While you drag from the resize corner, Atmos displays a live scale change. When you release the mouse, it commits the new scale to the widget settings.

This lets resizing feel fluid without turning the saved widget state into a constant stream of partial values.

Hidden behavior: resize is diagonal and additive

Atmos calculates resize changes from the combined horizontal and vertical drag distance, rather than from a dedicated isolated slider-like control.

That means the resize interaction feels more like pulling a corner outward or inward, which matches what users expect visually from a desktop resize affordance.

Snap-to-grid only affects final placement

Snap-to-grid does not force the widget to jump rigidly during every live drag frame.

Instead, the snap logic is applied when Atmos commits the widget’s new stored position.

That is a subtle but important design choice, because it keeps dragging from feeling stiff while still producing a cleaner final layout.

What snap-to-grid actually does

When snap-to-grid is enabled, Atmos rounds the widget’s normalized position to the nearest grid step before saving it.

That means the final widget location is aligned to a layout grid rather than left at an arbitrary freeform point.

This is useful if you want a more structured desktop composition.

Grid divisions control the density of the layout

Atmos also stores a grid division count for the snap system.

That value determines how fine or coarse the layout grid is. A lower division count creates a larger, looser grid. A higher division count creates a denser placement grid with more possible snapped positions.

So snap-to-grid is not just on or off. The grid itself has a configurable resolution.

Hidden behavior: the visual grid appears only in the right conditions

Atmos does not permanently draw the snap grid over your desktop.

The visual grid only appears when:

• edit mode is active
• snap-to-grid is enabled

That means the alignment helpers show up only when they are useful instead of cluttering the normal desktop.

The grid is square and spans the desktop overlay

The visible snap guide is drawn across the full widget overlay using lines and intersection dots.

The grid spacing is based on the configured division count, and the same step logic is used to support the saved snapped positions.

This makes the visual guide more than decorative. It reflects the actual alignment system behind the widget layout.

Widget positions are stored in normalized screen coordinates

Atmos stores widget positions as normalized values instead of raw pixel positions.

That means the stored position is based on relative screen placement rather than on one exact pixel coordinate.

This is a smart fit for a desktop overlay system because it helps widgets behave more consistently across different screen sizes and restoration flows.

Hidden behavior: final positions are clamped to safe bounds

After a drag is committed, Atmos also clamps the saved widget position into a bounded range instead of letting the widget drift infinitely off-screen.

That helps keep widgets recoverable and prevents layout accidents from turning into missing content.

Widget size is separate from widget type size

Atmos has both:

• a widget size category such as small, medium, or large
• a continuous widget scale value used for resize adjustments

That means users are not limited to a few rigid size presets once the widget is already on the desktop.

This gives edit mode more flexibility than a simple template picker.

Widget settings are saved automatically

The widget system autosaves changes, including:

• widget list changes
• enabled state
• snap-to-grid state
• grid division count
• widget movement
• widget settings updates

This makes edit mode feel lightweight because there is no heavy manual save step after every little adjustment.

Hidden behavior: widget layout settings are part of profile export too

Widget configuration is not just a local temporary convenience.

Atmos includes widget state, snap-to-grid state, and grid division settings in widget profile snapshots and import/export flows.

That means your widget layout logic can travel with a broader Atmos profile setup.

Why widget editing feels more polished than it looks

The widget system is doing a lot behind the scenes:

• separating visual overlay from input handling
• deciding whether an interaction is a tap, drag, or resize
• toggling widget selection
• showing temporary drag and resize feedback
• snapping final positions only when appropriate
• autosaving the result

That is why the experience feels calmer than many desktop widget systems that either overreact to every click or make layout changes feel awkward.

What users should take away

The practical behavior is:

• enter edit mode to manipulate widgets
• tap a widget to open or close its options panel
• drag a widget to reposition it
• drag the corner handle to resize it
• use snap-to-grid if you want more structured placement
• leave edit mode to cleanly end the session and preserve the result

Once you understand those rules, the widget editor becomes much easier to use intentionally.

It is not just a freeform desktop toy. It is a fairly structured editing system designed to make widget placement feel stable and deliberate.