dirty-state-tracking-guide.md

Dirty State Tracking

Track unsaved changes in PDF documents to prompt users before discarding modifications.

Quick Start

Use the cross-platform hasUnsavedChanges() method for simple dirty state checking:

final hasChanges = await document.hasUnsavedChanges();
if (hasChanges) {
  final shouldSave = await showSaveDialog();
  if (shouldSave) {
    await document.save();
  }
}

Cross-Platform API

Method	Description
hasUnsavedChanges()	Returns true if the document has any unsaved changes

Platform behavior:

• iOS: Checks document.hasDirtyAnnotations
• Android: Checks annotation, form, and bookmark providers
• Web: Checks instance.hasUnsavedChanges()

Platform-Specific APIs

iOS

Method	Description
iOSHasDirtyAnnotations()	Check if document has dirty annotations
iOSGetAnnotationIsDirty(pageIndex, annotationId)	Check if specific annotation is dirty
iOSSetAnnotationIsDirty(pageIndex, annotationId, isDirty)	Set annotation dirty state
iOSClearNeedsSaveFlag()	Clear the needs-save flag for all annotations

if (Platform.isIOS) {
  // Check document-level dirty state
  final hasDirty = await document.iOSHasDirtyAnnotations();

  // Check individual annotation
  final isDirty = await document.iOSGetAnnotationIsDirty(0, annotationId);

  // Mark annotation as clean
  await document.iOSSetAnnotationIsDirty(0, annotationId, false);

  // Clear needs-save flag after programmatic changes
  await document.iOSClearNeedsSaveFlag();
}

Android

Method	Description
androidHasUnsavedAnnotationChanges()	Check annotation provider for changes
androidHasUnsavedFormChanges()	Check form provider for changes
androidHasUnsavedBookmarkChanges()	Check bookmark provider for changes
androidGetBookmarkIsDirty(bookmarkId)	Check if specific bookmark is dirty
androidClearBookmarkDirtyState(bookmarkId)	Clear bookmark dirty state
androidGetFormFieldIsDirty(fieldName)	Check if specific form field is dirty

if (Platform.isAndroid) {
  // Check each provider
  final annotationsChanged = await document.androidHasUnsavedAnnotationChanges();
  final formsChanged = await document.androidHasUnsavedFormChanges();
  final bookmarksChanged = await document.androidHasUnsavedBookmarkChanges();

  // Check individual items
  final isDirty = await document.androidGetFormFieldIsDirty('fieldName');

  // Clear bookmark dirty state (only bookmarks can be cleared on Android)
  await document.androidClearBookmarkDirtyState(bookmarkId);
}

Web

Method	Description
webHasUnsavedChanges()	Check if web instance has unsaved changes

if (kIsWeb) {
  final hasChanges = await document.webHasUnsavedChanges();
}

Feature Matrix

Feature	Android	iOS	Web
hasUnsavedChanges()	✅	✅	✅
Document-level dirty check	✅	✅	✅
Per-annotation dirty check	❌	✅	❌
Set annotation dirty state	❌	✅	❌
Clear needs-save flag	Bookmarks only	✅	❌
Form changes check	✅	❌	❌
Per-form-field dirty check	✅	❌	❌
Bookmark changes check	✅	❌	❌
Per-bookmark dirty check	✅	❌	❌

Common Patterns

Prevent Accidental Data Loss

PopScope(
  canPop: !_hasUnsavedChanges,
  onPopInvokedWithResult: (didPop, result) async {
    if (didPop) return;
    final shouldDiscard = await _showDiscardDialog();
    if (shouldDiscard && mounted) {
      Navigator.of(context).pop();
    }
  },
  child: // your widget
)

Programmatic Changes Without Save Prompt (iOS)

// Add annotation programmatically
await document.addAnnotation(annotation);

// Clear needs-save flag so user isn't prompted
if (Platform.isIOS) {
  await document.iOSClearNeedsSaveFlag();
}