Draft PR - FitMode and layout enhancements

[enhancient]

Overview

This is a draft PR for an enhanced page layout system that provides support for more complex layouts and page/document scaling, and includes some 'out of the box' implementations for common layouts.

1. Page Layout System (pdf_page_layout.dart)

Extends upon the existing page layout system as follows:

• PdfPageLayout - Base class for all page layouts has been enhanced
  • Supports custom layout strategies via layoutBuilder callback
  • Provides calculateFitScale() for FitMode-aware scaling
  • Maintains backward compatibility with direct instantiation, but with a new helper argument added to the signature for backwards compatible page layouts:

  typedef PdfPageLayoutFunction =
   PdfPageLayout Function(List<PdfPage> pages, PdfViewerParams params, PdfLayoutHelper helper);

class PdfPageLayout {
  PdfPageLayout({required this.pageLayouts, required this.documentSize});
  
  // NEW: Dynamic layout calculation support
  final LayoutBuilder? layoutBuilder;
  
  // NEW: Automatic primary axis detection
  final Axis primaryAxis;
  
  // NEW: Built-in FitMode calculations
  double calculateFitScale(PdfLayoutHelper helper, FitMode mode, {int? pageNumber});
  
  // NEW: Page size calculations for different modes
  List<Size> calculatePageSizes({required PdfLayoutHelper helper, required FitMode mode});
  
  // ... plus helper methods for common operations
}

• PdfSpreadLayout - Abstract base for spread-aware layouts (facing pages, book mode)

  • Provides pageToSpreadIndex mapping for efficient page-to-spread lookups
  • Supports spread-specific scaling calculations
  • Setup to support future 'discrete' page transition mode [see separate PR that incorporates this]

• SinglePagesLayout - Single-column page layout (default)

  • Pages arranged in a single vertical or horizontal column
  • Independently scales pages of different sizes and aspect ratios according to FitMode for optimal viewing experience
  • Supports cross-axis centering of pages

• FacingPagesLayout - Facing pages (book-style) layout

  • Groups pages into spreads with optional cover page
  • Calculates scale based on spread width rather than individual page width

• PdfLayoutHelper - Utility class for viewport and margin calculations

  • Simplifies margin handling (boundary margins + content margins)
  • Provides convenient getters for available space calculations that custom PdfPageLayout classes can use

2. FitMode Support (pdf_viewer_params.dart)

Introduces FitMode enum for controlling how pages are scaled to fit the viewport:

• FitMode.fit - Fit entire page within viewport (shows whole page, may have letterboxing)
• FitMode.fill - Fill viewport on cross-axis (width for vertical scroll, height for horizontal)
• FitMode.cover - Fill viewport completely (may crop content on one axis)
• FitMode.none - No automatic scaling (1:1 scale)

FitMode.fit provides equivalent behavior to useAlternativeFitScaleAsMinScale, and the proposal is to deprecate the latter in preference to the former.

FitMode.cover provides equivalent behavior to the default scaling where useAlternativeFitScaleAsMinScale was false.

3. Scroll Thumb Enhancements (pdf_viewer_scroll_thumb.dart)

• Added visiblePageRangeBuilder for displaying page ranges (e.g., "1-4" for spreads) - also useful for other layouts where zooming out would display multiple pages at once
• Added useVisiblePageRange parameter to enable range display
• Automatically uses controller.visiblePageRange when available

pdfrx_page_layout_vertical.mov

pdfrx_page_layout_facing_pages.mov