diff --git a/resources/views/docs/mobile/4/digging-deeper/gestures.md b/resources/views/docs/mobile/4/digging-deeper/gestures.md index 847b521b..dd970970 100644 --- a/resources/views/docs/mobile/4/digging-deeper/gestures.md +++ b/resources/views/docs/mobile/4/digging-deeper/gestures.md @@ -38,6 +38,9 @@ and shrinks together, with no PHP involved during the gesture. To have a drag settle on set points when the finger lifts, like a row that slides aside to show its actions, give the gesture area [snap points](../edge-components/gesture-area#swipe-to-reveal). +A pinch or a double tap drives a shared value the same way, through the gesture area's `zoom`. That's how a photo +viewer zooms its photos. See [Zoomable images](../edge-components/gesture-area#zoomable-images). + ### Formulas Rather than bind the raw value everywhere, derive from it with a chainable formula. Each method returns a new diff --git a/resources/views/docs/mobile/4/edge-components/gesture-area.md b/resources/views/docs/mobile/4/edge-components/gesture-area.md index e8aa3b03..4107cd13 100644 --- a/resources/views/docs/mobile/4/edge-components/gesture-area.md +++ b/resources/views/docs/mobile/4/edge-components/gesture-area.md @@ -30,12 +30,13 @@ screen in your app and drag the card. - `pan-y` - A [`SharedValue`](../digging-deeper/gestures) that receives the vertical drag translation. Bind it, then read it from animatable props (`translate-y`, `opacity`, `scale`, …) on the children. - `pan-x` - The same for the horizontal drag translation. Bind one axis or both. -- `pinch` - A `SharedValue` that receives the pinch scale factor, where `1` is the content's own size. Read it from - `scale` on the children. -- `pinch-min` / `pinch-max` - The smallest and largest the pinch scale can go (optional, float). The limit is applied +- `zoom` - A `SharedValue` that receives the zoom scale, where `1` is the content's whole size. A pinch + drives it, and so does a [double tap](#double-tap-to-zoom). Read it from `scale` on the children. Before 4.9 the + zoom attributes were named `pinch`, `pinch-min`, `pinch-max` and `@pinchEnd`, and those names still work. +- `zoom-min` / `zoom-max` - The smallest and largest the scale can go (optional, float). The limit is applied as the fingers move, so the scale never runs past it and a pinch that changes direction responds straight away. -- `bounded` - Keep zoomed content on screen (optional, boolean). See - [Zoomable images](#zoomable-images). +- `bounded` - Keep zoomed content on screen, and leave drags it can't use to + whatever is around the area (optional, boolean). See [Zoomable images](#zoomable-images). - `content-ratio` - The content's width over height, for `bounded` (optional, float). The content is taken to be that shape fitted inside the area, which is where an image with `fit="contain"` draws. Leave it out when the content fills the area. @@ -57,7 +58,10 @@ interpolation formulas. - `@dragEnd` - Component method to call when the finger lifts after a drag. It gets the final translation on each axis as two floats, `x` then `y`. A bound axis reports its shared value, which with snap points is the point it settled on. An unbound axis reports how far the finger moved. -- `@pinchEnd` - Component method to call when the fingers lift after a pinch, with the final scale as a float. +- `@zoomEnd` - Component method to call when a zoom ends, with the final scale as a float. That's when the + fingers lift after a pinch, or when a [double tap's](#double-tap-to-zoom) zoom lands. +- `@doubleTap.zoom` - The scale a double tap zooms to (float). It isn't a component + method. See [Double tap to zoom](#double-tap-to-zoom). - `@swipe` - Component method to call on a quick swipe, with its direction as a string: `left`, `right`, `up` or `down`. @@ -74,6 +78,8 @@ A gesture area shares its touches with the scroll view around it and with the sy goes back. - A swipe across a pressable inside the area, or one around it, doesn't press it. On Android, before mobile-ui 0.9, it pressed it as well. +- A `bounded` area leaves a one-finger drag to whatever is around it, such as a pager or a scroll view, unless its + zoomed content has room to move that way. See [Who gets a drag](#who-gets-a-drag). ## Zoomable images @@ -82,18 +88,24 @@ A gesture area shares its touches with the scroll view around it and with the sy With `bounded`, the gesture area keeps zoomed content inside its own edges, the way a photo viewer does: - Zoomed in, the content pans until its edges meet the area's edges, and no further. -- On an axis where the zoomed content still fits, such as the height of a wide photo, it stays centered. At its own +- On an axis where the zoomed content still fits, such as the height of a wide photo, it stays centered. At its whole size it fits both ways, so it doesn't move at all. -- A drag past an edge moves with resistance, and the content springs back into place when the finger lifts. +- A drag past an edge moves with resistance, and the content springs back into place when the finger lifts. Inside + a pager or a scroll view, the rest of the drag [pages or scrolls instead](#who-gets-a-drag). - A pinch zooms around the point between the fingers, and two fingers pan as they pinch. +- Let go of a drag and the content carries on at the finger's speed, slowing to a stop, and bounces off an edge it + reaches. A finger held still before it lifts doesn't glide. `@dragEnd` is called as the finger lifts, with where + the content will come to rest. +- The area clips its content to its own frame, so zoomed content never draws over the elements around it, or over + the next page in a pager. -Bind both pan axes and the pinch, bind the content's transforms to the same values, and pass the image's shape as +Bind both pan axes and the zoom, bind the content's transforms to the same values, and pass the image's shape as `content-ratio`: @verbatim ```blade static @@ -109,7 +121,7 @@ Bind both pan axes and the pinch, bind the content's transforms to the same valu ``` @endverbatim -The shared values live on the component. Making fresh ones puts the image back at its own size, in the middle: +The shared values live on the component. Making fresh ones puts the image back at its whole size, in the middle: ```php use Native\Mobile\Edge\SharedValue; @@ -134,6 +146,129 @@ Pass its width over height so the bounds match the picture. +### Double tap to zoom + + + +Add `@doubleTap.zoom` to the area, with the scale a double tap zooms to: + +@verbatim +```blade static + +``` +@endverbatim + +A double tap at whole size zooms to that scale and brings the tapped point to the middle, as far as `bounded` lets it +go. A double tap on zoomed content takes it back to whole size, in the middle. Both ways animate over about a third +of a second, and `@zoomEnd` is called with the new scale once the zoom lands, the same as after a pinch. + +It needs `:zoom` bound. Like a pinch, it aims by moving the bound pans, so bind `pan-x` and `pan-y` as well. + +An `@event.modifier="value"` attribute isn't a PHP handler the way `@event="method"` is. Its value goes straight to +the phone, so `@doubleTap.zoom="2"` tells the area to zoom to a scale of 2 on a double tap, and the phone does that +without calling PHP. The value can be echoed, as in `@doubleTap.zoom="@{{ $level }}"`. A scale of `1` or less leaves +the double tap off. + +### Who gets a drag + + + +At whole size, a bounded area leaves one-finger drags to whatever is around it: a pager pages, a scroll view scrolls, +and the pan of a gesture area around it moves, such as a drag to close. Zoomed in, it takes a drag while the content +has room to move the way the finger is going, so the same drag that paged now pans the photo. Two fingers down are +always the area's, for a pinch. + +Zoomed content at an edge leaves a drag that way to a pager or scroll view around it, so a zoomed photo at its right +edge pages on a swipe left. It keeps the drag from a gesture area's pan, though. A drag to close only works at whole +size, so panning a zoomed photo up to its top edge doesn't start closing the viewer. + +Room to move means more than 2 points, and a zoom that ends a hair past 1x counts as whole size. Keep both pans +bound all the time. There's no need to unbind them, or to change the markup, when the zoom changes. + +When zoomed content reaches its edge part way through a drag and the finger keeps going, the rest of the drag moves +the pager or scroll view around it. A pager slides on to the next page, the way the Photos app does. With nothing +around to take the drag, the content moves past the edge with resistance and springs back when the finger lifts. + +Before mobile-ui 0.11, a bounded area with its pans bound took every one-finger drag, so a pager around it couldn't +page. + +### A photo viewer + + + +A horizontal [pager](pager) of photos, each one zoomable on its own page: + +@verbatim +```blade static + + @foreach ($photos as $i => $photo) + + + + @endforeach + +``` +@endverbatim + +At whole size a swipe sideways pages. Zoomed in, it pans the photo, and once the photo's edge is reached the same +swipe carries on into the next page. A drag down to close goes on a gesture area around the pager, with its own +`pan-y`, and the photos leave that drag to it while they're at whole size. + +Each photo has its own three shared values, kept on the component by its place in the list. `paged()` gives the +photo you left fresh ones, so it's back at whole size when you come back to it. With `report-on-settle`, `paged()` +is only called once the swipe has come to rest, so the photo doesn't jump back to whole size while it's still +sliding off screen: + +```php +use Native\Mobile\Edge\SharedValue; + +public array $photos = []; // each one ['url' => ..., 'width' => ..., 'height' => ...] + +public int $index = 0; + +public array $zooms = []; +public array $pansX = []; +public array $pansY = []; + +public function mount(): void +{ + // Load $this->photos, then give each photo its shared values. + + foreach (array_keys($this->photos) as $i) { + $this->rest($i); + } +} + +public function paged(int $index): void +{ + $this->rest($this->index); + $this->index = $index; +} + +private function rest(int $i): void +{ + $this->zooms[$i] = SharedValue::make(1.0); + $this->pansX[$i] = SharedValue::make(); + $this->pansY[$i] = SharedValue::make(); +} +``` + ## Swipe to reveal