feat: add annotation rendering support (Phase 7.1)

michaelstonis · michaelstonis · commit 483592d1a2a6 · 2025-11-24T21:32:14.000-06:00
- Add EnableAnnotationRendering property (default: true)
- Android: Full control via enableAnnotationRendering() configurator
  - Separated annotation rendering from link navigation
  - Triggers document reload when changed after load
  - Preserves current page on reload
- iOS: Controls annotation display via ShouldDisplay property
  - Iterates through all page annotations and sets visibility
  - Forces view refresh to update display immediately
  - Fully functional toggle on both platforms
- Add full property mapping in handlers for both platforms
- Sample app: Add PDF with annotations for testing
- Sample app: Add UI toggle button to enable/disable annotations
- Update documentation with Phase 7.1 complete status
diff --git a/FEATURE_ENHANCEMENT_PLAN.md b/FEATURE_ENHANCEMENT_PLAN.md
@@ -45,7 +45,7 @@ We aim to provide a consistent API across iOS and Android wherever reasonably po
 | Best quality (ARGB_8888)       | ✅                    | ✅ (default)  | ✅                     | ✅ Phase 4 Complete       |
 | Background color               | ✅                    | ✅            | ✅                     | ✅ Phase 4 Complete       |
 | **Annotations & Rendering**    |                       |               |                        |                           |
-| Annotation rendering           | ✅                    | ✅ (default)  | ❌                     | ✅ To Add (Phase 7)       |
+| Annotation rendering           | ✅                    | ✅ (default)  | ✅                     | ✅ Phase 7 Complete       |
 | Password protection            | ✅                    | ✅            | ✅                     | ✅ Phase 5.2 Complete     |
 | Custom drawing (onDraw)        | ✅                    | ✅            | ❌                     | **Advanced Feature**      |
 | Custom drawing all pages       | ✅                    | ✅            | ❌                     | **Advanced Feature**      |
@@ -167,11 +167,21 @@ We aim to provide a consistent API across iOS and Android wherever reasonably po
 
 **Goal:** Enable PDF annotation rendering and basic interaction
 
-#### 7.1 Annotation Rendering
-- Add `EnableAnnotationRendering` property
-- Render PDF annotations, forms, comments
-- **Android:** Use `enableAnnotationRendering()` configurator
-- **iOS:** Enabled by default, add toggle if possible
+**Status:** Phase 7.1 complete - Annotation rendering implemented
+
+#### 7.1 Annotation Rendering ✅ **COMPLETE**
+- ✅ Added `EnableAnnotationRendering` property (default: true)
+- ✅ **Android:** Uses `enableAnnotationRendering()` configurator
+  - Separated from link navigation (previously bundled)
+  - Triggers document reload when changed
+  - Preserves current page on reload
+- ✅ **iOS:** Controls annotation display via `ShouldDisplay` property
+  - Iterates through all page annotations and sets visibility
+  - Forces view refresh to update display
+  - Fully functional toggle on both platforms
+- ✅ Property mapping on both platforms
+- ✅ Sample app includes PDF with annotations for testing
+- ✅ Merged to main
 
 #### 7.2 Annotation Events
 - Add `AnnotationTappedEventArgs` with annotation details
@@ -318,9 +328,10 @@ For each phase:
 | Phase 5.1 | Display Mode | 0.5 days | ✅ Complete |
 | Phase 5.2 | Password Support | 0.5 days | ✅ Complete |
 | Phase 6 | Document Metadata | N/A | ❌ Cancelled |
-| Phase 7 | Annotations | 1 day | 📋 Planned |
+| Phase 7.1 | Annotation Rendering | 0.5 days | ✅ Complete |
+| Phase 7.2 | Annotation Events | 0.5 days | 📋 Planned |
 
-**Total remaining**: ~1 day for Phase 7
+**Total remaining**: ~0.5 days for Phase 7.2
 **Notes:** 
 - Night Mode feature removed from scope (iOS incompatibility)
 - Enhanced Metadata feature cancelled (Android library bug)
diff --git a/samples/MauiPdfViewerSample/PdfTestPage.xaml b/samples/MauiPdfViewerSample/PdfTestPage.xaml
@@ -18,6 +18,9 @@
                 <Button x:Name="LoadFileButton" 
                         Text="Load Sample PDF" 
                         Clicked="OnLoadFileClicked" />
+                <Button x:Name="LoadAnnotationFileButton" 
+                        Text="Load Annotations PDF" 
+                        Clicked="OnLoadAnnotationFileClicked" />
                 <Button x:Name="PrevPageButton" 
                         Text="◀ Prev" 
                         Clicked="OnPrevPageClicked"
@@ -48,6 +51,14 @@
                         Text="Single Page Continuous"
                         Clicked="OnToggleDisplayModeClicked" />
             </HorizontalStackLayout>
+
+            <!-- New Phase 7 Features -->
+            <HorizontalStackLayout Spacing="10" HorizontalOptions="Center">
+                <Label Text="Annotations:" VerticalOptions="Center" />
+                <Button x:Name="ToggleAnnotationsButton"
+                        Text="Enabled"
+                        Clicked="OnToggleAnnotationsClicked" />
+            </HorizontalStackLayout>
         </VerticalStackLayout>
 
         <!-- PDF Viewer -->
@@ -61,6 +72,7 @@
                          PageSpacing="10"
                          EnableAntialiasing="True"
                          UseBestQuality="True"
+                         EnableAnnotationRendering="True"
                          DocumentLoaded="OnDocumentLoaded"
                          PageChanged="OnPageChanged"
                          Error="OnError"
diff --git a/samples/MauiPdfViewerSample/PdfTestPage.xaml.cs b/samples/MauiPdfViewerSample/PdfTestPage.xaml.cs
@@ -46,6 +46,22 @@ private void OnLoadFileClicked(object? sender, EventArgs e)
         }
     }
 
+    private void OnLoadAnnotationFileClicked(object? sender, EventArgs e)
+    {
+        try
+        {
+            StatusLabel.Text = "Loading PDF with annotations...";
+            
+            // Load PDF with annotations from raw asset
+            PdfViewer.Source = PdfSource.FromAsset("sample_with_annotations.pdf");
+        }
+        catch (Exception ex)
+        {
+            StatusLabel.Text = $"Error: {ex.Message}";
+            DisplayAlert("Error", $"Failed to load PDF: {ex.Message}", "OK");
+        }
+    }
+
     private void OnPrevPageClicked(object? sender, EventArgs e)
     {
         if (PdfViewer.CurrentPage > 0)
@@ -129,4 +145,12 @@ private void OnToggleDisplayModeClicked(object? sender, EventArgs e)
         ToggleDisplayModeButton.Text = _displayModeNames[_displayModeIndex];
         StatusLabel.Text = $"Display mode: {_displayModeNames[_displayModeIndex]}";
     }
+
+    // New Phase 7 event handler
+    private void OnToggleAnnotationsClicked(object? sender, EventArgs e)
+    {
+        PdfViewer.EnableAnnotationRendering = !PdfViewer.EnableAnnotationRendering;
+        ToggleAnnotationsButton.Text = PdfViewer.EnableAnnotationRendering ? "Enabled" : "Disabled";
+        StatusLabel.Text = $"Annotation rendering: {(PdfViewer.EnableAnnotationRendering ? "Enabled" : "Disabled")}";
+    }
 }
diff --git a/src/MauiNativePdfView/Abstractions/IPdfView.cs b/src/MauiNativePdfView/Abstractions/IPdfView.cs
@@ -90,6 +90,13 @@ public interface IPdfView
     /// </summary>
     Color? BackgroundColor { get; set; }
 
+    /// <summary>
+    /// Gets or sets whether PDF annotations (forms, comments, highlights, etc.) should be rendered.
+    /// On Android: Controls whether annotations are displayed.
+    /// On iOS: Always enabled (PdfKit renders annotations by default).
+    /// </summary>
+    bool EnableAnnotationRendering { get; set; }
+
     /// <summary>
     /// Occurs when the document has finished loading.
     /// </summary>
diff --git a/src/MauiNativePdfView/PdfView.cs b/src/MauiNativePdfView/PdfView.cs
@@ -158,6 +158,16 @@ public class PdfView : View
             typeof(PdfView),
             null);
 
+    /// <summary>
+    /// Bindable property for annotation rendering.
+    /// </summary>
+    public static readonly BindableProperty EnableAnnotationRenderingProperty =
+        BindableProperty.Create(
+            nameof(EnableAnnotationRendering),
+            typeof(bool),
+            typeof(PdfView),
+            true);
+
     /// <summary>
     /// Gets or sets the PDF source to display.
     /// </summary>
@@ -293,6 +303,17 @@ public bool UseBestQuality
         set => SetValue(BackgroundColorProperty, value);
     }
 
+    /// <summary>
+    /// Gets or sets whether PDF annotations (forms, comments, highlights, etc.) should be rendered.
+    /// On Android: Controls whether annotations are displayed.
+    /// On iOS: Always enabled (PdfKit renders annotations by default).
+    /// </summary>
+    public bool EnableAnnotationRendering
+    {
+        get => (bool)GetValue(EnableAnnotationRenderingProperty);
+        set => SetValue(EnableAnnotationRenderingProperty, value);
+    }
+
     /// <summary>
     /// Gets the current page number (0-based).
     /// </summary>
diff --git a/src/MauiNativePdfView/Platforms/Android/PdfViewAndroid.cs b/src/MauiNativePdfView/Platforms/Android/PdfViewAndroid.cs
@@ -32,6 +32,7 @@ public class PdfViewAndroid : IPdfView, IDisposable
     private bool _enableAntialiasing = true;
     private bool _useBestQuality = true;
     private Color? _backgroundColor;
+    private bool _enableAnnotationRendering = true;
     private int _currentPage = 0;
     private int _pageCount = 0;
 
@@ -215,6 +216,20 @@ public Color? BackgroundColor
         }
     }
 
+    public bool EnableAnnotationRendering
+    {
+        get => _enableAnnotationRendering;
+        set
+        {
+            if (_enableAnnotationRendering != value)
+            {
+                _enableAnnotationRendering = value;
+                if (_pageCount > 0) // Document is loaded
+                    Reload();
+            }
+        }
+    }
+
     public event EventHandler<DocumentLoadedEventArgs>? DocumentLoaded;
     public event EventHandler<PageChangedEventArgs>? PageChanged;
     public event EventHandler<PdfErrorEventArgs>? Error;
@@ -298,10 +313,14 @@ private void ConfigureAndLoad(PDFView.Configurator configurator, int pageToResto
         // Note: UseBestQuality sets rendering quality (ARGB_8888 vs RGB_565)
         // This is handled by the PDFView configuration automatically based on device capabilities
 
+        if (_enableAnnotationRendering)
+        {
+            configurator.EnableAnnotationRendering(true);
+        }
+
         if (_enableLinkNavigation)
         {
-            configurator.EnableAnnotationRendering(true)
-                       .LinkHandler(new LinkHandlerImpl(this));
+            configurator.LinkHandler(new LinkHandlerImpl(this));
         }
 
         configurator.Load();
diff --git a/src/MauiNativePdfView/Platforms/Android/PdfViewHandler.cs b/src/MauiNativePdfView/Platforms/Android/PdfViewHandler.cs
@@ -33,6 +33,7 @@ public partial class PdfViewHandler : ViewHandler<PdfView, PDFView>
         [nameof(PdfView.EnableAntialiasing)] = MapEnableAntialiasing,
         [nameof(PdfView.UseBestQuality)] = MapUseBestQuality,
         [nameof(PdfView.BackgroundColor)] = MapBackgroundColor,
+        [nameof(PdfView.EnableAnnotationRendering)] = MapEnableAnnotationRendering,
     };
 
     /// <summary>
@@ -263,6 +264,14 @@ private static void MapBackgroundColor(PdfViewHandler handler, PdfView view)
         }
     }
 
+    private static void MapEnableAnnotationRendering(PdfViewHandler handler, PdfView view)
+    {
+        if (handler._pdfViewWrapper != null)
+        {
+            handler._pdfViewWrapper.EnableAnnotationRendering = view.EnableAnnotationRendering;
+        }
+    }
+
     #endregion
 
     #region Command Mappers
diff --git a/src/MauiNativePdfView/Platforms/iOS/PdfViewHandler.cs b/src/MauiNativePdfView/Platforms/iOS/PdfViewHandler.cs
@@ -27,7 +27,8 @@ public partial class PdfViewHandler : ViewHandler<PdfView, PdfKit.PdfView>
         [nameof(PdfView.DefaultPage)] = MapDefaultPage,
         [nameof(PdfView.EnableAntialiasing)] = MapEnableAntialiasing,
         [nameof(PdfView.UseBestQuality)] = MapUseBestQuality,
-        [nameof(PdfView.BackgroundColor)] = MapBackgroundColor
+        [nameof(PdfView.BackgroundColor)] = MapBackgroundColor,
+        [nameof(PdfView.EnableAnnotationRendering)] = MapEnableAnnotationRendering
     };
 
     public static CommandMapper<PdfView, PdfViewHandler> CommandMapper = new(ViewCommandMapper)
@@ -252,6 +253,14 @@ public static void MapBackgroundColor(PdfViewHandler handler, PdfView view)
         }
     }
 
+    public static void MapEnableAnnotationRendering(PdfViewHandler handler, PdfView view)
+    {
+        if (handler._pdfViewWrapper != null)
+        {
+            handler._pdfViewWrapper.EnableAnnotationRendering = view.EnableAnnotationRendering;
+        }
+    }
+
     public static void MapGoToPage(PdfViewHandler handler, PdfView view, object? args)
     {
         if (handler._pdfViewWrapper != null && args is int pageIndex)
diff --git a/src/MauiNativePdfView/Platforms/iOS/PdfViewiOS.cs b/src/MauiNativePdfView/Platforms/iOS/PdfViewiOS.cs
@@ -18,6 +18,7 @@ public class PdfViewiOS : IPdfView, IDisposable
     private PdfScrollOrientation _scrollOrientation = PdfScrollOrientation.Vertical;
     private int _defaultPage = 0;
     private bool _documentLoaded = false;
+    private bool _enableAnnotationRendering = true;
 
     public PdfViewiOS()
     {
@@ -202,6 +203,19 @@ public Color? BackgroundColor
         }
     }
 
+    public bool EnableAnnotationRendering
+    {
+        get => _enableAnnotationRendering;
+        set
+        {
+            if (_enableAnnotationRendering != value)
+            {
+                _enableAnnotationRendering = value;
+                UpdateAnnotationVisibility();
+            }
+        }
+    }
+
     public event EventHandler<DocumentLoadedEventArgs>? DocumentLoaded;
     public event EventHandler<PageChangedEventArgs>? PageChanged;
     public event EventHandler<PdfErrorEventArgs>? Error;
@@ -339,6 +353,9 @@ private void LoadDocument()
                 var currentPageIndex = _defaultPage > 0 && _defaultPage < pageCount ? _defaultPage : 0;
                 PageChanged?.Invoke(this, new PageChangedEventArgs(currentPageIndex, pageCount));
 
+                // Apply annotation visibility setting
+                UpdateAnnotationVisibility();
+
                 // Fire rendered event after a short delay to ensure rendering is complete
                 if (!_documentLoaded)
                 {
@@ -363,6 +380,29 @@ private void LoadDocument()
         }
     }
 
+    private void UpdateAnnotationVisibility()
+    {
+        if (_pdfView.Document == null)
+            return;
+
+        // Iterate through all pages and hide/show annotations
+        for (nint i = 0; i < _pdfView.Document.PageCount; i++)
+        {
+            var page = _pdfView.Document.GetPage(i);
+            if (page?.Annotations != null)
+            {
+                foreach (var annotation in page.Annotations)
+                {
+                    // Set annotation to hidden or visible
+                    annotation.ShouldDisplay = _enableAnnotationRendering;
+                }
+            }
+        }
+
+        // Force refresh the view
+        _pdfView.SetNeedsDisplay();
+    }
+
     private void OnPageChangedNotification(NSNotification notification)
     {
         if (_pdfView.Document != null && _pdfView.CurrentPage != null)
