Bump version to 1.2.5

- Update version numbers in gradle.properties, app/build.gradle.kts, and README.md - Add changelog entry for v1.2.5 with page navigation callback fixes - Update VERSION_HISTORY.md with new version information and upgrade guide - Prepare for release with comprehensive documentation updates

Author: rhariskumar3

README.md

@@ -39,7 +39,7 @@ To install AndroidPDFPreview, add the following dependency to your project's Gra
 
 ```
 dependencies {
- implementation 'io.github.rhariskumar3:pdfpreview:1.2.4'
+ implementation 'io.github.rhariskumar3:pdfpreview:1.2.5'
 }
 ```
 

app/build.gradle.kts

@@ -23,7 +23,7 @@ android {
  minSdk = (property("minSdk") as String).toInt()
  targetSdk = (property("compileSdk") as String).toInt()
  versionCode = 1
- versionName = "1.2.4"
+ versionName = "1.2.5"
 
  ndk {
  abiFilters += listOf("arm64-v8a", "armeabi-v7a", "x86", "x86_64")

docs/CHANGELOG.md

@@ -5,6 +5,88 @@ All notable changes to AndroidPDFPreview will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.5] - 2025-10-29 - Critical Bug Fix: Page Navigation Callbacks & Page Snap
+
+### Fixed
+
+- **🐛 Page Navigation Callback Issues**
+ - Fixed `onPageChanged()` callback not firing after scroll/animation completion
+ - Added `loadPageByOffset()` calls in animation completion handlers (`handleAnimationEnd()` and `performFling()`)
+ - Ensures page change detection occurs after all navigation operations (scroll, fling, jumpTo, page snap)
+ - `onPageChanged()` now fires reliably for all navigation scenarios
+
+- **📊 Page Snap Animation Callbacks**
+ - Fixed `onPageScrolled()` reporting intermediate page numbers during page snap animations
+ - Added check in `updateScrollUIElements()` to skip callbacks during active page snap animations
+ - Prevents confusing page number jumping during snap animations when `pageSnap=true`
+ - Page callbacks now only report final settled page positions
+
+- **🎯 Initial Load Page Snapping**
+ - Fixed pages not centering with page snap enabled during first load with default page
+ - Added `performPageSnap()` calls to `jumpTo()` for non-animated jumps when page snap is enabled
+ - Pages now properly center on initial load when `pageSnap=true` configuration is used
+ - Improved `loadComplete()` with enhanced logging for debugging initial load issues
+
+- **⚡ Animation State Detection**
+ - Fixed compilation error with incorrect `pdfAnimator.isRunning` property reference
+ - Replaced with correct `pdfAnimator.isFlinging` property that checks for active animations
+ - Proper detection of page snap animations and flings for callback suppression
+
+### Technical Details
+
+- **Animation Completion Handling**:
+ - `PdfAnimator.handleAnimationEnd()` now calls `pdfView.loadPageByOffset()` to detect page changes
+ - `PdfAnimator.performFling()` now calls `pdfView.loadPageByOffset()` when fling completes
+ - Ensures `onPageChanged()` fires after both programmatic animations and user scroll flings
+
+- **Page Snap Callback Prevention**:
+ - `PDFView.updateScrollUIElements()` skips intermediate callbacks when `isPageSnap && pdfAnimator.isFlinging`
+ - Prevents page number jumping during snap animations while maintaining final position callbacks
+ - Uses consistent page calculation logic across all callback scenarios
+
+- **Initial Load Improvements**:
+ - `PDFView.jumpTo()` now performs page snapping for non-animated jumps when page snap is enabled
+ - Enhanced `loadComplete()` with better logging for initial page jump operations
+ - Proper initialization sequence ensures page centering on document load
+
+### Migration Guide
+
+No code changes required. This is an internal bug fix that improves callback reliability and page snap behavior.
+
+**What's Fixed:**
+
+```kotlin
+// Page change callbacks now work correctly in all scenarios
+pdfView.configureView {
+ pageSnap(true)
+ pageNavigationEventListener(object : PageNavigationEventListener {
+ override fun onPageChanged(page: Int, pageCount: Int) {
+ // ✅ NOW FIRES: After scroll completion
+ // ✅ NOW FIRES: After animation completion 
+ // ✅ NOW FIRES: After page snap settles
+ }
+ 
+ override fun onPageScrolled(page: Int, positionOffset: Float) {
+ // ✅ NO MORE JUMPING: Stable page numbers during snap animations
+ // ✅ ACCURATE: Reports correct page during scroll
+ }
+ })
+}
+```
+
+**Root Cause:**
+
+- Animation completion didn't trigger page change detection
+- Page snap animations caused intermediate callback reports
+- Initial load timing issues prevented proper page positioning
+- Missing `loadPageByOffset()` calls in animation end handlers
+
+```gradle
+dependencies {
+ implementation 'io.github.rhariskumar3:pdfpreview:1.2.5'
+}
+```
+
 ## [1.2.4] - 2025-10-28 - Critical Bug Fix: Page Calculation Accuracy with Page Snap
 
 ### Fixed

docs/VERSION_HISTORY.md

@@ -4,17 +4,18 @@ This document provides a quick overview of all AndroidPDFPreview releases.
 
 ## 📋 Current Version
 
-**[1.2.4](./CHANGELOG.md#124---2025-10-28---critical-bug-fix-page-calculation-accuracy-with-page-snap)** - Latest Release (October 28, 2025)
+**[1.2.5](./CHANGELOG.md#125---2025-10-29---critical-bug-fix-page-navigation-callbacks--page-snap)** - Latest Release (October 29, 2025)
 
-- Fixed `onPageScrolled()` reporting incorrect page numbers during page snap animations
-- Accurate page position tracking with `pageSnap=true` configuration
-- Consistent page detection across scroll gestures and callbacks
-- Improved callback reliability during scroll deceleration
+- Fixed `onPageChanged()` callback not firing after scroll/animation completion
+- Fixed `onPageScrolled()` reporting intermediate pages during page snap animations
+- Fixed pages not centering with page snap enabled during first load
+- Improved page navigation callback reliability across all scenarios
 
 ## 📚 Version History
 
 | Version | Release Date | Type | Key Features |
 |-----------|--------------|-------|------------------------------------------------------------------------------------|
+| **1.2.5** | 2025-10-29 | Patch | Critical bug fix: page navigation callbacks & page snap behavior |
 | **1.2.4** | 2025-10-28 | Patch | Critical bug fix: page calculation accuracy with page snap enabled |
 | **1.2.3** | 2025-10-28 | Patch | Critical bug fix: page navigation callbacks now fire correctly after manual scroll |
 | **1.2.2** | 2025-10-24 | Minor | Performance optimization: smart tile loading, scroll pre-rendering, zoom listener |
@@ -29,7 +30,8 @@ This document provides a quick overview of all AndroidPDFPreview releases.
 
 ## 🔄 Version Status
 
-- ✅ **1.2.4** - Current (Recommended)
+- ✅ **1.2.5** - Current (Recommended)
+- ✅ **1.2.4** - Previous (Still supported)
 - ✅ **1.2.3** - Previous (Still supported)
 - ✅ **1.2.2** - Previous (Still supported)
 - ✅ **1.2.1** - Previous (Still supported)
@@ -44,15 +46,15 @@ This document provides a quick overview of all AndroidPDFPreview releases.
 
 ```gradle
 dependencies {
- implementation 'io.github.rhariskumar3:pdfpreview:1.2.4'
+ implementation 'io.github.rhariskumar3:pdfpreview:1.2.5'
 }
 ```
 
 ### Previous Version
 
 ```gradle
 dependencies {
- implementation 'io.github.rhariskumar3:pdfpreview:1.2.3'
+ implementation 'io.github.rhariskumar3:pdfpreview:1.2.4'
 }
 ```
 
@@ -64,6 +66,25 @@ dependencies {
 
 ## 🚀 Upgrade Guide
 
+### From 1.2.4 to 1.2.5
+
+- **Compatibility**: ✅ Fully backward compatible
+- **Breaking Changes**: None
+- **Action Required**: None - just update the version number
+- **Benefits**:
+ - `onPageChanged()` callback now fires after scroll/animation completion
+ - `onPageScrolled()` no longer reports intermediate pages during page snap animations
+ - Pages properly center with page snap enabled during first load
+ - Improved page navigation callback reliability across all scenarios
+
+```gradle
+// Old
+implementation 'io.github.rhariskumar3:pdfpreview:1.2.4'
+
+// New
+implementation 'io.github.rhariskumar3:pdfpreview:1.2.5'
+```
+
 ### From 1.2.3 to 1.2.4
 
 - **Compatibility**: ✅ Fully backward compatible
@@ -237,8 +258,8 @@ implementation 'io.github.rhariskumar3:pdfpreview:1.0.8'
 
 ## 📊 Release Statistics
 
-- **Total Releases**: 9 versions
-- **Latest Release**: October 28, 2025
+- **Total Releases**: 10 versions
+- **Latest Release**: October 29, 2025
 - **Release Frequency**: Regular updates with improvements
 - **Stability**: Stable and production-ready
 

gradle.properties

@@ -24,7 +24,7 @@ SONATYPE_HOST=S01
 RELEASE_SIGNING_ENABLED=true
 POM_GROUP_ID=io.github.rhariskumar3
 POM_ARTIFACT_ID=pdfpreview
-POM_VERSION=1.2.4
+POM_VERSION=1.2.5
 POM_PACKAGING=aar
 POM_NAME=pdfpreview
 POM_DESCRIPTION=AndroidPDFPreview is a lightweight and easy-to-use SDK that enables you to display and interact with PDF documents in your Android apps