@quran.ws/qvp-react-native 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/README.md +86 -32
  2. package/android/build.gradle +16 -8
  3. package/android/src/main/java/ws/quran/qvp/rn/Codes.kt +34 -0
  4. package/android/src/main/java/ws/quran/qvp/rn/Marshal.kt +78 -30
  5. package/android/src/main/java/ws/quran/qvp/rn/QvpModule.kt +105 -50
  6. package/android/src/main/java/ws/quran/qvp/rn/QvpPageViewManager.kt +1 -0
  7. package/android/src/main/java/ws/quran/qvp/rn/QvpRnPageView.kt +55 -14
  8. package/android/src/main/java/ws/quran/qvp/rn/QvpRnWords.kt +26 -0
  9. package/ios/QvpModule.m +167 -0
  10. package/ios/QvpModule.swift +508 -0
  11. package/ios/QvpRnBytes.swift +66 -0
  12. package/ios/QvpRnCodes.swift +33 -0
  13. package/ios/QvpRnMarshal.swift +360 -0
  14. package/ios/QvpRnPageView.swift +467 -0
  15. package/ios/QvpRnPassageView.swift +160 -0
  16. package/ios/vendor/QvpEngine.json +4 -0
  17. package/ios/vendor/QvpKit/QvpDress.swift +390 -0
  18. package/ios/vendor/QvpKit/QvpEngine.swift +55 -0
  19. package/ios/vendor/QvpKit/QvpPage.swift +469 -0
  20. package/ios/vendor/QvpKit/QvpPageCache.swift +176 -0
  21. package/ios/vendor/QvpKit/QvpPageCanvas.swift +1031 -0
  22. package/ios/vendor/QvpKit/QvpPageView.swift +711 -0
  23. package/ios/vendor/QvpKit/QvpPassage.swift +240 -0
  24. package/ios/vendor/QvpKit/QvpViewPolicy.swift +26 -0
  25. package/ios/vendor/QvpKit/QvpZoom.swift +200 -0
  26. package/ios/vendor/QvpKit/QvpZoomSpring.swift +22 -0
  27. package/ios/vendor/QvpKit/Types.swift +440 -0
  28. package/ios/vendor-qvpkit.sh +36 -0
  29. package/package.json +10 -3
  30. package/qvp-react-native.podspec +97 -0
  31. package/src/codes.ts +33 -0
  32. package/src/index.tsx +171 -55
@@ -0,0 +1,240 @@
1
+ // A range of complete ayahs, or a surah's basmalah, laid out on rows away from its page, over the
2
+ // C ABI in qvp.h.
3
+ // The engine measures and places every word; this file marshals the calls. See docs/API.md.
4
+ import Foundation
5
+ import CoreGraphics
6
+ import QvpFFI
7
+
8
+ /// Where the rows of a passage start.
9
+ public enum QvpPassageAlign: UInt8, Sendable {
10
+ /// At the right edge, as Arabic text starts.
11
+ case right = 0
12
+ /// In the middle of the width.
13
+ case center = 1
14
+ /// Across the width: every row but the last opens its word gaps until it reaches both edges,
15
+ /// never past `QvpPassageSpec.maxStretch`. What is left over is split between the two sides,
16
+ /// so the last row, a one-word row and a capped row are centred.
17
+ case justified = 2
18
+ }
19
+
20
+ /// What a layout of a passage asks for. Lengths are layout points.
21
+ public struct QvpPassageSpec: Equatable, Sendable {
22
+ /// The width of the rows. Zero or less puts the whole passage on one row, as wide as it is.
23
+ public var width: Float
24
+ /// Layout points per page unit. It shrinks only when one word and its signs are wider than
25
+ /// the rows. To size a passage by its printed line, divide by `QvpPassage.lineSpacing`.
26
+ public var scale: Float
27
+ /// The distance between two rows' baselines, as a multiple of the printed one. At least 1.
28
+ public var lineSpacing: Float
29
+ /// The empty margin on every side.
30
+ public var padding: Float
31
+ /// Where each row starts.
32
+ public var align: QvpPassageAlign
33
+ /// The most rows to show. Zero shows every row.
34
+ public var maxRows: Int
35
+ /// After a cut, place the medallion of the passage's last ayah after the ellipsis.
36
+ public var keepAyahMark: Bool
37
+ /// The width that the host needs for its ellipsis after a cut.
38
+ public var ellipsisWidth: Float
39
+ /// How far a justified row's gaps may open, as a multiple of the passage's usual air between
40
+ /// two words. A negative value lifts the cap.
41
+ public var maxStretch: Float
42
+
43
+ /// Make a spec; the defaults put the passage on one row at the printed size.
44
+ public init(width: Float = 0, scale: Float = 1, lineSpacing: Float = 1, padding: Float = 2, align: QvpPassageAlign = .right,
45
+ maxRows: Int = 0, keepAyahMark: Bool = false, ellipsisWidth: Float = 0,
46
+ maxStretch: Float = QvpDefaults.REFLOW_MAX_STRETCH) {
47
+ self.width = width; self.scale = scale; self.lineSpacing = lineSpacing; self.padding = padding; self.align = align
48
+ self.maxRows = maxRows; self.keepAyahMark = keepAyahMark; self.ellipsisWidth = ellipsisWidth
49
+ self.maxStretch = maxStretch
50
+ }
51
+ }
52
+
53
+ /// One row of a laid-out passage, in layout points.
54
+ public struct QvpPassageRow: Equatable {
55
+ /// The box of the row's ink, and the height its words sit on.
56
+ public let x0: Float, y0: Float, x1: Float, y1: Float, baseline: Float
57
+ }
58
+
59
+ /// One word of a laid-out passage with the signs that go with it, in layout points.
60
+ public struct QvpPassageWord: Equatable {
61
+ /// The word's key and the page it is printed on.
62
+ public let surah: Int, ayah: Int, word: Int, page: Int
63
+ /// The row the word is on, from 0.
64
+ public let row: Int
65
+ /// The box of the word and its signs.
66
+ public let x0: Float, y0: Float, x1: Float, y1: Float
67
+ /// The box of the word alone, without its signs: the word that closes an ayah leaves its
68
+ /// medallion out. An underline under the word reads this box.
69
+ public let wordX0: Float, wordY0: Float, wordX1: Float, wordY1: Float
70
+ /// The word's key, `surah:ayah:word`, as Kotlin's `QvpPassageWord.wordKey`.
71
+ public var wordKey: String { "\(surah):\(ayah):\(word)" }
72
+ }
73
+
74
+ /// The bounds of one ayah that a layout shows, in layout points.
75
+ public struct QvpPassageAyah: Equatable {
76
+ /// The ayah, and the box of its shown words.
77
+ public let surah: Int, ayah: Int, x0: Float, y0: Float, x1: Float, y1: Float
78
+ }
79
+
80
+ /// One path that a passage layout draws: its page, its index on that page, and which of
81
+ /// `QvpPassageLayout.placements` it goes under.
82
+ public struct QvpPassageDraw: Equatable {
83
+ /// The page number. Draw the path with that page's geometry (`QvpPage.buildPaths()`).
84
+ public let page: Int
85
+ /// The path's index on its page.
86
+ public let path: Int
87
+ /// The index of its placement.
88
+ public let placement: Int
89
+ }
90
+
91
+ /// A laid-out passage. A point `(x, y)` of a path draws at
92
+ /// `scale · (kx · x + dx), scale · (ky · y + dy)`, with the path's placement.
93
+ public struct QvpPassageLayout: Equatable {
94
+ /// The size of the layout, padding included, and the scale it was laid out at.
95
+ public let width: Float, height: Float, scale: Float
96
+ /// The distance between two rows' baselines, page units, before a row moves down for its ink.
97
+ public let lineSpacing: Float
98
+ /// The rows, top to bottom.
99
+ public let rows: [QvpPassageRow]
100
+ /// The words shown, in reading order.
101
+ public let words: [QvpPassageWord]
102
+ /// The ayahs with at least one word shown.
103
+ public let ayahs: [QvpPassageAyah]
104
+ /// Every path to draw, in drawing order.
105
+ public let draws: [QvpPassageDraw]
106
+ /// What `QvpPassageDraw.placement` indexes.
107
+ public let placements: [QvpPlacement]
108
+ /// The layout shows fewer words than the passage has.
109
+ public let isTruncated: Bool
110
+ /// Where the host draws its ellipsis after a cut: from the last row's top to its baseline.
111
+ public let ellipsis: CGRect?
112
+
113
+ /// Fill the layout into `ctx` with its top-left corner at (`x`, `y`), in the context's fill
114
+ /// colour. `pages` maps a page number to the open page the passage was loaded from, which
115
+ /// holds the outlines. A draw whose page is not in the map, or is closed, is skipped. The
116
+ /// ellipsis after a cut is the host's to draw, at `ellipsis`.
117
+ public func draw(in ctx: CGContext, pages: [Int: QvpPage], x: CGFloat = 0, y: CGFloat = 0) {
118
+ let s = CGFloat(scale)
119
+ var cur = -1
120
+ ctx.saveGState()
121
+ for d in draws {
122
+ guard let page = pages[d.page], page.isOpen else { continue }
123
+ if d.placement != cur {
124
+ // A point p of a path lands at scale · (k · p + d): the placement first, then the scale.
125
+ let q = d.placement < placements.count ? placements[d.placement] : .identity
126
+ ctx.restoreGState(); ctx.saveGState()
127
+ ctx.concatenate(CGAffineTransform(a: s * CGFloat(q.kx), b: 0, c: 0, d: s * CGFloat(q.ky),
128
+ tx: x + s * CGFloat(q.dx), ty: y + s * CGFloat(q.dy)))
129
+ cur = d.placement
130
+ }
131
+ let paths = page.buildPaths()
132
+ guard d.path < paths.count else { continue }
133
+ ctx.addPath(paths[d.path])
134
+ ctx.fillPath(using: page.pathEvenOdd(d.path) ? .evenOdd : .winding)
135
+ }
136
+ ctx.restoreGState()
137
+ }
138
+ }
139
+
140
+ /// One ayah of a passage, with its text from the page's own word records.
141
+ public struct QvpPassageText: Equatable {
142
+ /// The ayah and its text.
143
+ public let surah: Int, ayah: Int, text: String
144
+ }
145
+
146
+ /// A contiguous range of complete ayahs, ready to lay out at any width. It copies what it
147
+ /// needs from its pages, so the pages can be closed after it is made.
148
+ public final class QvpPassage {
149
+ private var h: OpaquePointer?
150
+
151
+ /// The ayahs in reading order.
152
+ public let ayahs: [QvpPassageText]
153
+ /// The printed line spacing of the passage's first word, in page units. Every word of the
154
+ /// passage has that size.
155
+ public let lineSpacing: Float
156
+ /// The last layout.
157
+ public private(set) var currentLayout: QvpPassageLayout?
158
+
159
+ /// Load the ayahs `from` to `to` of `surah` from the pages that print them, in any order.
160
+ /// Throws when an ayah is missing or incomplete, a page is given twice, or the range has more
161
+ /// than 4,096 words.
162
+ public convenience init(pages: [QvpPage], surah: Int, from: Int, to: Int? = nil) throws {
163
+ let to = to ?? from
164
+ // Every engine call on a closed page traps; the engine checks the range itself.
165
+ guard pages.allSatisfy(\.isOpen), (1...Int(UInt16.max)).contains(surah), (1...Int(UInt16.max)).contains(from),
166
+ (1...Int(UInt16.max)).contains(to) else { throw QvpError.badPassage }
167
+ let handles: [OpaquePointer?] = pages.map { $0.p }
168
+ let h = handles.withUnsafeBufferPointer {
169
+ qvp_passage_load($0.baseAddress, UInt32(truncatingIfNeeded: $0.count), UInt16(truncatingIfNeeded: surah), UInt16(truncatingIfNeeded: from), UInt16(truncatingIfNeeded: to))
170
+ }
171
+ guard let h else { throw QvpError.badPassage }
172
+ self.init(h, surah: surah, from: from)
173
+ }
174
+
175
+ /// Load the basmalah printed above `surah` from whichever of the pages prints it. It lays out
176
+ /// as one piece on one row and has no ayahs and no words; its line spacing is its page's, so
177
+ /// it is sized by the printed line as an ayah is. Throws for surah 1, whose basmalah is its
178
+ /// first ayah, for surah 9, which has none, and when no page given prints it.
179
+ public convenience init(basmalahOf surah: Int, pages: [QvpPage]) throws {
180
+ guard pages.allSatisfy(\.isOpen), (1...Int(UInt16.max)).contains(surah) else { throw QvpError.badPassage }
181
+ let handles: [OpaquePointer?] = pages.map { $0.p }
182
+ let h = handles.withUnsafeBufferPointer {
183
+ qvp_passage_load_basmalah($0.baseAddress, UInt32(truncatingIfNeeded: $0.count), UInt16(truncatingIfNeeded: surah))
184
+ }
185
+ guard let h else { throw QvpError.badPassage }
186
+ self.init(h, surah: surah, from: 1)
187
+ }
188
+
189
+ private init(_ h: OpaquePointer, surah: Int, from: Int) {
190
+ self.h = h
191
+ ayahs = (0..<Int(qvp_passage_ayah_count(h))).map { i in
192
+ var s = QvpStr(); qvp_passage_ayah_text(h, UInt32(truncatingIfNeeded: i), &s)
193
+ return QvpPassageText(surah: surah, ayah: from + i, text: s.string)
194
+ }
195
+ lineSpacing = qvp_passage_line_spacing(h)
196
+ }
197
+ deinit { close() }
198
+ /// Free the native passage. A second call does nothing.
199
+ public func close() { if let p = h { qvp_passage_free(p); h = nil } }
200
+ /// False once `close()` has run.
201
+ public var isOpen: Bool { h != nil }
202
+ /// The engine handle. Internal: the wrapper marshals through it, no app ever sees it.
203
+ /// A call on a closed passage stops the program with the fatal error `QvpPassage is closed`.
204
+ var p: OpaquePointer { guard let h else { fatalError("QvpPassage is closed") }; return h }
205
+
206
+ /// Lay the passage out. `nil` when the spec is out of range; the last layout then stays.
207
+ @discardableResult
208
+ public func layout(_ spec: QvpPassageSpec) -> QvpPassageLayout? {
209
+ let p = self.p
210
+ guard spec.maxRows >= 0 else { return nil }
211
+ var s = QvpFFI.QvpPassageSpec(width: spec.width, scale: spec.scale, line_spacing: spec.lineSpacing, padding: spec.padding,
212
+ align: spec.align.rawValue, keep_ayah_mark: spec.keepAyahMark ? 1 : 0, _pad: (0, 0),
213
+ max_rows: UInt32(truncatingIfNeeded: spec.maxRows), ellipsis_width: spec.ellipsisWidth, max_stretch: spec.maxStretch)
214
+ var out = QvpFFI.QvpPassageLayout()
215
+ guard qvp_passage_layout(p, &s, &out) != 0 else { return nil }
216
+ let rows: [QvpFFI.QvpPassageRow] = collect(max(1, Int(out.n_rows))) { o, c in qvp_passage_rows(p, o, c) }
217
+ let words: [QvpFFI.QvpPassageWord] = collect(max(1, Int(out.n_words))) { o, c in qvp_passage_words(p, o, c) }
218
+ let ayahs: [QvpFFI.QvpPassageAyah] = collect(max(1, Int(out.n_ayahs))) { o, c in qvp_passage_ayahs(p, o, c) }
219
+ let draws: [UInt32] = collect(max(3, Int(out.n_draws) * 3)) { o, c in qvp_passage_draw_list(p, o, c / 3) * 3 }
220
+ let placements: [Float] = collect(64) { o, c in qvp_passage_placements(p, o, c / 4) * 4 }
221
+ let layout = QvpPassageLayout(
222
+ width: out.width, height: out.height, scale: out.scale, lineSpacing: out.line_spacing,
223
+ rows: rows.map { QvpPassageRow(x0: $0.x0, y0: $0.y0, x1: $0.x1, y1: $0.y1, baseline: $0.baseline) },
224
+ words: words.map { QvpPassageWord(surah: Int($0.surah), ayah: Int($0.ayah), word: Int($0.word), page: Int($0.page), row: Int($0.row),
225
+ x0: $0.x0, y0: $0.y0, x1: $0.x1, y1: $0.y1,
226
+ wordX0: $0.word_x0, wordY0: $0.word_y0, wordX1: $0.word_x1, wordY1: $0.word_y1) },
227
+ ayahs: ayahs.map { QvpPassageAyah(surah: Int($0.surah), ayah: Int($0.ayah), x0: $0.x0, y0: $0.y0, x1: $0.x1, y1: $0.y1) },
228
+ draws: stride(from: 0, to: draws.count, by: 3).map { QvpPassageDraw(page: Int(draws[$0]), path: Int(draws[$0 + 1]), placement: Int(draws[$0 + 2])) },
229
+ placements: stride(from: 0, to: placements.count, by: 4).map {
230
+ QvpPlacement(dx: placements[$0], dy: placements[$0 + 1], kx: placements[$0 + 2], ky: placements[$0 + 3])
231
+ },
232
+ isTruncated: out.is_truncated != 0,
233
+ ellipsis: out.is_truncated != 0
234
+ ? CGRect(x: CGFloat(out.ellipsis_x0), y: CGFloat(out.ellipsis_y0),
235
+ width: CGFloat(out.ellipsis_x1 - out.ellipsis_x0), height: CGFloat(out.ellipsis_y1 - out.ellipsis_y0))
236
+ : nil)
237
+ currentLayout = layout
238
+ return layout
239
+ }
240
+ }
@@ -0,0 +1,26 @@
1
+ // The view-state helpers both iOS renderers share. They are platform conveniences
2
+ // (docs/API-PARITY.md) and decide nothing the engine could decide: every number comes from the
3
+ // engine's view and zoom calls.
4
+ import CoreGraphics
5
+ import QvpFFI
6
+
7
+ /// The view-state helpers that both iOS renderers share. Every number comes from the engine.
8
+ public enum QvpViewPolicy {
9
+ /// The engine's own ceiling on the magnifying glass, `QVP_DEFAULT_MAX_ZOOM`: what
10
+ /// `QvpPageView.maxZoom` and `QvpCanvasController.maxZoom` start at.
11
+ public static let maxZoom: CGFloat = CGFloat(QvpDefaults.MAX_ZOOM)
12
+
13
+ /// The scale a magnifying pinch lands on, from the engine (`qvp_view_zoom_about`): held
14
+ /// between `fit`, the page's settled size, and `ceiling`, the host's own. A pinch magnifies
15
+ /// the print and never shrinks the page inside the screen, so a ceiling under the floor is
16
+ /// the floor. A ceiling of 0 or less is the engine's own.
17
+ public static func clampZoom(_ scale: CGFloat, fit: CGFloat, ceiling: CGFloat) -> CGFloat {
18
+ CGFloat(QvpView(scale: Float(scale)).zoomAbout(focalX: 0, focalY: 0, factor: 1, min: Float(fit), max: Float(ceiling)).scale)
19
+ }
20
+ /// How many pages a released drag turns, in the muṣḥaf's own order: +1 the page after this
21
+ /// one, -1 the page before it, nil when it is not a swipe. The engine decides, so no platform
22
+ /// can read the book backwards.
23
+ public static func swipeDirection(translation t: CGSize, velocity v: CGSize) -> Int? {
24
+ qvpSwipePages(translation: t, velocity: v)
25
+ }
26
+ }
@@ -0,0 +1,200 @@
1
+ // The reader's zoom control: what a pinch does to the page.
2
+ //
3
+ // A pinch can scale the printed page, the way it scales a photograph, or ask for bigger ink at
4
+ // the same page width — which is reflow: fewer words to a row, the rest moved down. Which of
5
+ // those a pinch means, where it lands, when it commits and what holds the reader's place across
6
+ // the relayout is the engine's, so every platform pinches alike.
7
+ import CoreGraphics
8
+ import QvpFFI
9
+
10
+ /// What a pinch does to the page.
11
+ public enum QvpZoomMode: UInt32 {
12
+ /// The pinch lands on one of the page's own zoom steps and the page reflows onto it. What a
13
+ /// reader gets unless a host asks otherwise.
14
+ case stepped = 0
15
+ /// The pinch drives the reflow zoom itself, up to the page's own limit.
16
+ case continuous = 1
17
+ /// The pinch scales the laid-out page as it stands. The rows never change.
18
+ case magnify = 2
19
+ }
20
+
21
+ /// Where the reader's zoom control stands. A host keeps this beside its view transform, and the
22
+ /// default is the control a page opens on: stepped, on the printed page.
23
+ public struct QvpZoom: Equatable {
24
+ /// True once the reader has zoomed in, by either road: the view magnified past the size the
25
+ /// page is fitted at, or the page reflowed above the printed size.
26
+ public func isZoomed(_ view: QvpView, fitScale: Float) -> Bool {
27
+ var z = c, v = view.c
28
+ return qvp_zoom_is_zoomed(&z, &v, fitScale) != 0
29
+ }
30
+
31
+ public var mode: QvpZoomMode
32
+ /// 0 is the printed page, 1 upwards the page's own steps.
33
+ public var step: Int
34
+ /// The size in force, 1 at the printed page, whichever field the mode steers by.
35
+ public var zoom: Float
36
+ public init(mode: QvpZoomMode = .stepped, step: Int = 0, zoom: Float = 1) { self.mode = mode; self.step = step; self.zoom = zoom }
37
+ var c: QvpFFI.QvpZoom { QvpFFI.QvpZoom(mode: mode.rawValue, step: UInt32(truncatingIfNeeded: step), zoom: zoom) }
38
+ init(_ z: QvpFFI.QvpZoom) { self.mode = QvpZoomMode(rawValue: z.mode) ?? .stepped; self.step = Int(z.step); self.zoom = z.zoom }
39
+ }
40
+
41
+ /// How many pages a released drag turns, in reading order: +1 the page after this one, -1 the
42
+ /// page before it, nil when the drag is not a swipe. A muṣḥaf is read right to left, so a flick
43
+ /// to the right turns to the next page — the engine says so, rather than each platform deciding.
44
+ public func qvpSwipePages(translation t: CGSize, velocity v: CGSize) -> Int? {
45
+ let pages = qvp_swipe_pages(Float(t.width), Float(t.height), Float(v.width), Float(v.height))
46
+ return pages == 0 ? nil : Int(pages)
47
+ }
48
+
49
+ /// What a sideways drag on a page means.
50
+ public enum QvpSideways {
51
+ /// The drag pans the page, or it turns the page.
52
+ case pan, turnPage
53
+ }
54
+
55
+ /// What a gesture produced: the control to keep, the view to draw with, and whether the page was
56
+ /// laid out again under it. A host redraws its overlays when `relaid` is true.
57
+ public struct QvpZoomChange {
58
+ /// The control to keep, the view to draw with, and whether the page was laid out again.
59
+ public let zoom: QvpZoom, view: QvpView, relaid: Bool
60
+ }
61
+
62
+ /// `QvpPage.layoutInkBand`: the band of the layout a host keeps drawn, in layout px. It sits on
63
+ /// the screen at `view.offsetY + view.scale·y`.
64
+ public struct QvpInkBand: Equatable {
65
+ public var top: Float, height: Float
66
+ public init(top: Float, height: Float) { self.top = top; self.height = height }
67
+ }
68
+
69
+ /// Pan and zoom over a laid-out page: a point `p` in layout points draws at `offset + scale·p`.
70
+ public struct QvpView: Equatable {
71
+ public var scale: Float, offsetX: Float, offsetY: Float
72
+ public init(scale: Float = 1, offsetX: Float = 0, offsetY: Float = 0) { self.scale = scale; self.offsetX = offsetX; self.offsetY = offsetY }
73
+ var c: QvpFFI.QvpView { QvpFFI.QvpView(scale: scale, offset_x: offsetX, offset_y: offsetY) }
74
+ init(_ v: QvpFFI.QvpView) { self.scale = v.scale; self.offsetX = v.offset_x; self.offsetY = v.offset_y }
75
+
76
+ /// This view zoomed by `factor` about a point of the viewport, with the scale held between
77
+ /// `min` and `max`: the point under the fingers stays under them. A limit of 0 is the
78
+ /// engine's own, and a ceiling under the floor is the floor. A host hands this the view and
79
+ /// the focal point the pinch began on and the factor of the whole gesture.
80
+ public func zoomAbout(focalX: Float, focalY: Float, factor: Float, min: Float = 0, max: Float = 0) -> QvpView {
81
+ var v = c, out = QvpFFI.QvpView()
82
+ qvp_view_zoom_about(&v, focalX, focalY, factor, min, max, &out)
83
+ return QvpView(out)
84
+ }
85
+ /// This view moved by a drag, in view points.
86
+ public func pan(dx: Float, dy: Float) -> QvpView {
87
+ var v = c, out = QvpFFI.QvpView()
88
+ qvp_view_pan(&v, dx, dy, &out)
89
+ return QvpView(out)
90
+ }
91
+ }
92
+
93
+ extension QvpPage {
94
+ /// The same control under another policy, keeping the size the reader is already at.
95
+ public func zoomMode(_ spec: QvpLayoutSpec, _ zoom: QvpZoom, _ mode: QvpZoomMode) -> QvpZoom {
96
+ var s = spec.c, z = zoom.c, out = QvpFFI.QvpZoom()
97
+ qvp_zoom_mode(p, &s, &z, mode.rawValue, &out)
98
+ return QvpZoom(out)
99
+ }
100
+ /// One frame of a pinch. `factor` is the distance between the fingers against their distance
101
+ /// when they went down — the whole gesture every time, not the change since the last frame —
102
+ /// and `focal` the point between them, in view points.
103
+ public func zoomPinch(_ spec: QvpLayoutSpec, _ zoom: QvpZoom, _ view: QvpView, factor: Float, focalX: Float, focalY: Float) -> QvpZoomChange {
104
+ var s = spec.c, z = zoom.c, v = view.c, out = QvpFFI.QvpZoomChange()
105
+ qvp_zoom_pinch(p, &s, &z, &v, factor, focalX, focalY, &out)
106
+ // the engine laid the page out inside the call: keep the cached layout with it
107
+ if out.relaid != 0 { readLayout() }
108
+ return QvpZoomChange(zoom: QvpZoom(out.zoom), view: QvpView(out.view), relaid: out.relaid != 0)
109
+ }
110
+ /// The control moved straight to a step: a size button, a double tap, a reset. Step 0 is the
111
+ /// printed page.
112
+ public func zoomToStep(_ spec: QvpLayoutSpec, _ zoom: QvpZoom, _ step: Int, _ view: QvpView) -> QvpZoomChange {
113
+ var s = spec.c, z = zoom.c, v = view.c, out = QvpFFI.QvpZoomChange()
114
+ qvp_zoom_to_step(p, &s, &z, UInt32(truncatingIfNeeded: step), &v, &out)
115
+ if out.relaid != 0 { readLayout() }
116
+ return QvpZoomChange(zoom: QvpZoom(out.zoom), view: QvpView(out.view), relaid: out.relaid != 0)
117
+ }
118
+ /// The same control on this page: what the reader was reading at, carried onto the page they
119
+ /// turned to. A step carries as a step, because every page's steps are its own; a free zoom
120
+ /// carries as a size, held inside what this page can reach.
121
+ public func zoomCarried(_ spec: QvpLayoutSpec, _ zoom: QvpZoom) -> QvpZoom {
122
+ var s = spec.c, z = zoom.c, out = QvpFFI.QvpZoom()
123
+ qvp_zoom_carried(p, &s, &z, &out)
124
+ return QvpZoom(out)
125
+ }
126
+ /// The reflow zoom one step of this page's control means; step 0 is the printed page.
127
+ public func zoomAtStep(_ spec: QvpLayoutSpec, _ step: Int) -> Float {
128
+ var s = spec.c
129
+ return qvp_zoom_at_step(p, &s, UInt32(truncatingIfNeeded: step))
130
+ }
131
+ /// What a sideways drag on this page means: pan it, or turn the page.
132
+ public func sidewaysDrag(_ zoom: QvpZoom, _ view: QvpView, fitScale: Float) -> QvpSideways {
133
+ var z = zoom.c, v = view.c
134
+ return qvp_sideways_drag(p, &z, &v, fitScale) == 1 ? .turnPage : .pan
135
+ }
136
+ /// `spec` with this control's zoom in it: what the host lays out, draws and hit-tests with.
137
+ /// The host's other reflow knobs come back as it set them, on the printed page too, where
138
+ /// the zoom is 0 and they wait for the next pinch.
139
+ public func zoomSpec(_ spec: QvpLayoutSpec, _ zoom: QvpZoom) -> QvpLayoutSpec {
140
+ var s = spec.c, z = zoom.c, out = QvpFFI.QvpLayoutSpec()
141
+ qvp_zoom_spec(p, &s, &z, &out)
142
+ // The control owns the reflow zoom alone, and the engine hands every other field back as
143
+ // the host set it. So the host's own spec carries every knob, and only the zoom is read
144
+ // back. On the printed page the zoom is 0 and the knobs stay: dropping them there would
145
+ // leave the pinch that leaves the printed page to lay it out with the engine's defaults.
146
+ var spec = spec
147
+ if out.reflow_zoom > 0 || spec.reflow != nil {
148
+ var reflow = spec.reflow ?? QvpReflowSpec(zoom: 0)
149
+ reflow.zoom = out.reflow_zoom
150
+ spec.reflow = reflow
151
+ }
152
+ return spec
153
+ }
154
+ /// Where a point of the viewport lands in the laid-out page: how a host turns a touch into
155
+ /// a `hitTestView`. The inverse of `offset + scale·p`.
156
+ public func viewToLayout(_ view: QvpView, _ viewX: Float, _ viewY: Float) -> (x: Float, y: Float) {
157
+ var v = view.c
158
+ var out = [Float](repeating: 0, count: 2)
159
+ qvp_view_to_layout(p, &v, viewX, viewY, &out)
160
+ return (out[0], out[1])
161
+ }
162
+ /// Which band of the current layout to keep drawn for `view` and a viewport: the whole page
163
+ /// when it fits, otherwise two screens around the reader. The top moves in steps, so a pan
164
+ /// inside one step redraws nothing; pass `top` and `top + height` to `layoutDrawList`.
165
+ /// `maxHeight` is the tallest band the host can draw and `maxPixels` the pixels it keeps for
166
+ /// one, both in viewport px; 0 takes `QvpDefaults.MAX_INK_HEIGHT` and no pixel limit. The
167
+ /// pixel limit never takes the band below one screen.
168
+ public func layoutInkBand(_ view: QvpView, viewportW: Float, viewportH: Float, maxHeight: Float = 0, maxPixels: Float = 0) -> QvpInkBand {
169
+ var v = view.c, out = QvpFFI.QvpInkBand()
170
+ qvp_layout_ink_band(p, &v, viewportW, viewportH, maxHeight, maxPixels, &out)
171
+ return QvpInkBand(top: out.top, height: out.height)
172
+ }
173
+ /// The band a view draws into one bitmap, in view points down the page: `layoutInkBand` for
174
+ /// a viewport measured in points, with the bitmap's limits in device pixels made points.
175
+ /// A bitmap is at most 16384 rows, which is `16384 / displayScale` points, and `maxPixels`
176
+ /// is the points the view keeps for it, its width times its height. `viewScale` is the
177
+ /// view's scale as the view holds it, so the points come back on the view's own grid. The
178
+ /// height is at least one point.
179
+ func inkBandPoints(_ view: QvpView, viewScale: CGFloat, viewportW: CGFloat, viewportH: CGFloat,
180
+ displayScale: CGFloat, maxPixels: CGFloat) -> (top: CGFloat, height: CGFloat) {
181
+ let s = max(displayScale, 1)
182
+ let b = layoutInkBand(view, viewportW: Float(viewportW), viewportH: Float(viewportH),
183
+ maxHeight: Float(16384 / s), maxPixels: Float(maxPixels))
184
+ return (CGFloat(b.top) * viewScale, max(CGFloat(b.height) * viewScale, 1))
185
+ }
186
+ /// Hold the content against the viewport: centre an axis it does not fill, cover the
187
+ /// viewport on an axis it overflows, so no drag opens a blank strip beside the page.
188
+ public func viewClamp(_ view: QvpView, contentW: Float, contentH: Float, viewportW: Float, viewportH: Float) -> QvpView {
189
+ var v = view.c, out = QvpFFI.QvpView()
190
+ qvp_view_clamp(&v, contentW, contentH, viewportW, viewportH, &out)
191
+ return QvpView(out)
192
+ }
193
+ /// The view that holds a point inside a word at a place on the screen, then clamps: how a
194
+ /// pinch keeps its place when the layout reflows under it.
195
+ public func viewAnchor(_ view: QvpView, word: Int, nx: Float, ny: Float, toX: Float, toY: Float, viewportW: Float, viewportH: Float) -> QvpView {
196
+ var v = view.c, out = QvpFFI.QvpView()
197
+ qvp_view_anchor(p, &v, UInt32(truncatingIfNeeded: word), nx, ny, toX, toY, viewportW, viewportH, &out)
198
+ return QvpView(out)
199
+ }
200
+ }
@@ -0,0 +1,22 @@
1
+ // Release animation for `zoomSpringsBack`: the view transform eases from where the pinch
2
+ // left it to the fitted one. Shared by QvpPageView (display link) and QvpCanvasController
3
+ // (main-actor task), so both views move the same way.
4
+ import Foundation
5
+ import CoreGraphics
6
+
7
+ struct QvpZoomSpring {
8
+ typealias ViewTransform = (scale: CGFloat, offsetX: CGFloat, offsetY: CGFloat)
9
+ static let duration = 0.25
10
+
11
+ let from: ViewTransform
12
+ let to: ViewTransform
13
+ /// Seconds, on the same clock as the `now` passed to `value(at:)`.
14
+ let start: Double
15
+
16
+ /// The transform at `now`, and whether it has arrived.
17
+ func value(at now: Double) -> (transform: ViewTransform, done: Bool) {
18
+ let t = min(max((now - start) / Self.duration, 0), 1)
19
+ let e = CGFloat(1 - pow(1 - t, 3)) // ease-out cubic
20
+ return ((from.scale + (to.scale - from.scale) * e, from.offsetX + (to.offsetX - from.offsetX) * e, from.offsetY + (to.offsetY - from.offsetY) * e), t >= 1)
21
+ }
22
+ }