Add EPUBNavigatorViewController's viewport
#612
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
There was a problem hiding this comment.
Pull Request Overview
This pull request adds a new viewport property to the EPUB navigator to expose information about visible reading order indices and positions, and updates several APIs to replace direct use of links with reading order indices. Key changes include:
- Introduction of the ReadingOrder typealias and ReadingOrderIndices to represent resource position data.
- Updates to locator and progression computations to work with reading order indices.
- Adjustments in several navigator view classes (EPUBSpreadView, EPUBSpread, EPUBNavigatorViewController, etc.) to improve consistency and readability.
Reviewed Changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| Support/Carthage/Readium.xcodeproj/project.pbxproj | Added ReadingOrder.swift file reference to the project. |
| Sources/Navigator/ReadingOrder.swift | New typealiases for ReadingOrder and ReadingOrderIndices have been introduced. |
| Sources/Navigator/EPUB/Scripts/src/utils.js | Updated scroll handling logic for clearer progression reporting. |
| Sources/Navigator/EPUB/EPUBSpreadView.swift | Changed focusedResource type and progression() return type to use reading order indices. |
| Sources/Navigator/EPUB/EPUBSpread.swift | Refactored spread logic to retrieve indices instead of links, ensuring consistency in JSON output. |
| Sources/Navigator/EPUB/EPUBNavigatorViewController.swift | Introduced a viewport structure and updated location computation logic to include viewport data. |
| Sources/Navigator/EPUB/EPUBReflowableSpreadView.swift | Updated spread view logic to use reading order indices for navigation. |
| Sources/Navigator/Audiobook/AudioNavigator.swift | Added @mainactor context to playback task for improved thread safety. |
| CHANGELOG.md | Updated changelog with the new viewport property and related navigator improvements. |
Comments suppressed due to low confidence (3)
Sources/Navigator/EPUB/EPUBNavigatorViewController.swift:137
- Consider using the existing typealias 'ReadingOrderIndices' instead of 'ClosedRange<[Link].Index>' for consistency and clarity.
public var readingOrderIndices: ClosedRange<[Link].Index>
Sources/Navigator/EPUB/EPUBSpreadView.swift:47
- [nitpick] Since the variable now holds an index rather than a full resource, consider renaming 'focusedResource' to 'focusedResourceIndex' for improved clarity.
private(set) var focusedResource: ReadingOrder.Index?
Sources/Navigator/EPUB/EPUBSpreadView.swift:345
- [nitpick] Returning '0 ..< 0' to represent an empty progression range might be unclear; consider defining a named constant (e.g. EMPTY_PROGRESSION) to improve readability and maintainability.
return 0 ..< 0
mickael-menu
force-pushed
the
epub/viewport
branch
from
9e5e0e9 to
eabebc0
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Added
Navigator
viewportproperty of anEPUBNavigatorViewControllerto obtain information about the visible portion of the publication, including the visible positions and reading order indices.The initial use case that motivated this PR is the need to display a range of visible positions to the user (e.g.,
5-6 of 120). This helps prevent confusion when turning pages "skips" several positions.I initially considered adding a second locator representing the "last visible locator", but this solution has some issues:
Locatoris not typed for each navigator. We want to move away from usingLocatorin the APIs and keep it as a serialization and exchange format only.position, but itsprogressionwill actually be the beginning of the next "screen page" (as it is the same as the last scroll progression of the current screen page). Therefore the locator would contain two incompatible values.After thinking more about this problem, I believe we should separate the current location (e.g. used for restoring the reading progression) from information about the rendering, which could actually contain more information that the last visible position (e.g. the list of reading order items currently displayed).
In this PR I added a new
viewportproperty in the EPUB navigator which can be used to report information about the visible portion of a publication in the navigator. Currently it contains only two informations:positions: ClosedRange<Int>- a range of visible positions, e.g5...6readingOrderIndices: ClosedRange<ReadingOrder.Index>- a contiguous range of indexes of the visible resources from thereadingOrder.@qnga @JayPanoz @chocolatkey I would love to get your opinion on this as we will likely need to align the implementations at some point.