feat(api): chrome().viewerPreferences() — page mode / layout / window on open#243
Merged
Conversation
…/ layout / window) A document could not say how a reader should present it on open — open the bookmark panel, use a two-column layout, show the title in the window — so a bookmarked document still opened to a bare page with the outline hidden. chrome().viewerPreferences(DocumentViewerPreferences) writes page mode, page layout, and the window-chrome flags (displayDocTitle, hideToolbar, hideMenubar, fitWindow, centerWindow) to the PDF document catalog. DocumentPageMode.USE_OUTLINES opens the bookmark panel — it pairs with bookmark(...) on sections, and DocumentViewerPreferences.openOutline() is a one-line preset. Threaded through the existing chrome path (SessionChromeApi -> DocumentChromeOptions -> DocumentOutputOptions -> translator -> backend -> post-processor) as a third document-global option alongside metadata and protection; the multi-section combined document takes it from the first section that sets it. Viewer preferences are advisory and PDF-only — other backends ignore them, and a document that sets none does not touch the catalog, so existing output is byte-for-byte unchanged. Tests: ViewerPreferencesTest asserts the catalog dictionary (not pixels) — USE_OUTLINES page mode, two-column layout, the window flags incl. an explicit false still writing the /ViewerPreferences dict, page-mode-only writing no dict, no-preferences leaving the catalog at its defaults, and the multi-section first-section-wins rule. Example: ViewerPreferencesExample (a guide that opens with its bookmark panel).
The bookmark() that USE_OUTLINES opens the panel for now exists on container flow builders (sections and containers), not only sections — widen the openOutline() Javadoc accordingly.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Why
A document couldn't say how a reader should present it on open — open the bookmark panel, use a two-column layout, show the title in the window. So a bookmarked document (the just-merged container
bookmark(...), #242) still opened to a bare page with the outline hidden. This is the second half of G7.What changed
chrome().viewerPreferences(DocumentViewerPreferences)writes page mode, page layout, and the window-chrome flags (displayDocTitle,hideToolbar,hideMenubar,fitWindow,centerWindow) to the PDF document catalog.DocumentPageMode.USE_OUTLINESopens the bookmark panel — pairs withbookmark(...);DocumentViewerPreferences.openOutline()is a one-line preset. New enumsDocumentPageMode/DocumentPageLayout(document.style).SessionChromeApi→DocumentChromeOptions→DocumentOutputOptions→PdfOutputOptionsTranslator→PdfFixedLayoutBackend→PdfDocumentPostProcessor) as a third document-global option alongside metadata and protection; the multi-section combined document takes it from the first section that sets it.DocumentOutputOptionscontract).Lane: canonical API + chrome thread. Purely additive → japicmp-safe — the public
apply(...)signatures are untouched (viewer prefs go through a new standaloneapplyViewerPreferences), andDocumentOutputOptions's new 5th component ships behind a re-declared 4-arg back-compat constructor.Verification
./mvnw test -pl .— green, 0 changed visual baselines → a document that sets no viewer preferences never touches the catalog../mvnw -P japicmp verify— binary-compatible.ViewerPreferencesTest(7) — asserts the catalog dictionary (not pixels, since viewer prefs are advisory):USE_OUTLINESpage mode, two-column layout, the window flags incl. an explicitfalsestill writing the/ViewerPreferencesdict, page-mode-only writing no dict, no-preferences leaving the catalog at its defaults, and the multi-section first-section-wins rule. Enum mapping verified against PDFBox 3.0.7 (USE_THUMBNAILS → PageMode.USE_THUMBS).anyFlaggate; it drove the multi-section + explicit-false +hideMenubar/centerWindowtests.ViewerPreferencesExample+ committed preview: a guide that opens with its bookmark panel showing (get_toc+ catalog page modeUseOutlinesverified).With #242, this completes G7 (containers as outline targets + the reader opening straight to them).