Proposal: Decorator API

[mickael-menu]

See the full proposal

This proposal introduces a new Navigator API to draw decorations on top of publications, in a media type agnostic way.

A variety of features need to draw user interface elements (decorations) over a publication's content, such as:

• highlighting a text selection
• displaying search results
• underlining spoken text with speech synthesis
• annotating a piece of content with an icon or button
• drawing side marks in the margin

The actual rendering routines depend on the media type of the decorated resources. We can simplify reading apps significantly by providing a media type agnostic Navigator API to handle decorations.

[chrfalch]

Great work! I've looked through your proposal and it seems (on first glance) like a flexible and generic way to handle and extend a navigator with decorations.

Would be interesting to see the API that the navigator is expected to implement to support this. Would diffing and rendering decorators be calculated by each navigator, or is this something that will be done for the navigator through a helper class?

[qnga]

Overall, I like the idea! Since the same topics occur in several places, comments are quite randomly ordered, sorry.

[mickael-menu]

@chrfalch Thanks!

Would be interesting to see the API that the navigator is expected to implement to support this. Would diffing and rendering decorators be calculated by each navigator, or is this something that will be done for the navigator through a helper class?

On iOS, there's no native diff algorithm before iOS 13 (it's used by Diffable Data Sources). But on Android there's one with Jetpack. I think the best approach would be a helper class, ideally using a native API. That's what I've implemented for iOS.

[qnga]

To summarise the discussion in comments, enabling or disabling interactions would be simpler on the basis of decoration groups. On Android, it might be done registering a listener for a specific group or not. I'm not sure how it could be implemented on iOS.

[mrifni]

this is great work.