[Documentation] Locator -> Location -> progression and totalProgression properties calculation

[vedat73]

Hi, I want to understand how progression and totalProgression properties of Locator -> Location are calculated when a word/words selected within a publications chapter. In this documentation link I did not see anything about it. Since I want to make epub reader library migration of my app to readium, it is important to know the formula of those properties. I will make data transformation for pre-stored users data. Thanks in advance for any info.

[mickael-menu]

What do you mean exactly by "when a word/words selected within a publications chapter."?

• totalProgression is never used to locate a position in the book, it's only used to display the location to the user.
• progression in EPUB is generally the scroll progression in the web view.
• If you have the text context (highlight, before and after) it's the most accurate way of locating a selection in a book. You don't even need the progression.

[vedat73]

hi @mickael-menu thanks for reply. Let me explain the question in a little detail.
When we select a word or words within the book, we can get the selected info through navigator.currentSelection . In this selection info there is an instance of R2Shared.Locator struct. In this Locator instance there is bunch of properties such as :

• href
• type
• title
• locations -> (progression, totalProgression, position etc.)
• text -> (before, highlight, after)

I thought that it also needs to define locations info to be able to display highlighted text. So I've asked about calculations of progression, totalProgression.

But as I understood from your reply, since we have text information and it sub informations (before, highlight, after) we do not need to define the locations information to be able to display the highlighted text on the screen. So only informations we need :

• href
• type
• text

the rest could be ignored.

Apart from all this, totalProgression is the scroll progression based on the entire book. And progression value is scroll progression based on a chapter.

Please clarify me if everything were understood correctly.

[mickael-menu]

That's right. When you use navigator.currentSelection, all the words on the visible page will have the same progression: the scroll progression of the current page.

As you can see below, we first take into account text, then locations.fragments (for HTML IDs) and finally the locations.progression, when resolving a Locator.

swift-toolkit/Sources/Navigator/EPUB/EPUBReflowableSpreadView.swift

Lines 270 to 278 in 06dbf83

	if locator.text.highlight != nil {
	scroll(toLocator: locator, completion: completion)
	// FIXME: find the first fragment matching a tag ID (need a regex)
	} else if let id = locator.locations.fragments.first, !id.isEmpty {
	scroll(toTagID: id, completion: completion)
	} else {
	let progression = locator.locations.progression ?? 0
	scroll(toProgression: progression, completion: completion)
	}

As long as you have any of these informations, we will find the location. The text is more reliable especially if you have a long highlight and also before/after. If you have a single word in highlight, there will be many false positive.