# Driver Behavior

## Default Mode

The default mode is multitouch scrolling. Run explicitly with:

```bash
surface-dial-renewed --mode multitouch
```

Regular wheel mode exists for fallback/testing:

```bash
surface-dial-renewed --mode wheel
```

## Normal Rotation

Normal Dial rotation emits a synthetic two-finger touchpad scroll through
`Surface Dial Renewed Touchpad`.

The driver starts a virtual two-finger contact on the first rotation event,
moves both virtual fingers vertically, and ends the touch gesture after no
rotation has arrived for 2 seconds.

The 2 second hold is intentional. Very slow physical Dial movement can emit
sparse `REL_DIAL` events. If the virtual fingers are lifted too quickly, libinput
can treat those sparse movements as many tiny gestures and ignore them. Holding
the contact makes slow and precise movement accumulate into one gesture.

## Sensitivity Selector

Hold the Dial down and rotate to change sensitivity.

- Range: `1/32` through `32/32`
- Default: `7/32`
- Step threshold: `48` raw Dial units per sensitivity level
- Display: KDE OSD text, falling back to notification
- Haptics: one buzz when entering the selector, one buzz per accepted level

While the button is held, rotation never scrolls. If a multitouch scroll gesture
is active when the button is pressed, it is ended before sensitivity adjustment.

## Sensitivity Scaling

The sensitivity level maps to milli-pixels per raw Dial unit:

```text
500 + (level - 1) * 250
```

This means level 1 is `0.5` virtual coordinate units per raw Dial unit, level 7
is `2.0`, and level 32 is `8.25`.

The driver stores fractional remainders while a gesture is active. A nonzero raw
Dial event is rounded away from zero if it would otherwise produce no integer
coordinate movement.

## Haptics

Haptics are deliberately limited:

- Enter sensitivity selector: buzz once.
- Change sensitivity level: buzz once.

Normal scrolling does not buzz. It was tested and removed because it was
distracting and hard to align with physical rotation consistently.

## OSD

On KDE, the driver calls:

```text
org.kde.plasmashell /org/kde/osdService org.kde.osdService.showText
```

The displayed text is:

```text
Surface Dial sensitivity N/32
```

KDE exposes polished volume/brightness OSD methods, but those are semantically
volume/brightness-specific. The generic custom progress API is not callable as a
normal method on this system, so the driver uses text OSD instead.