From 8bcd611a3315dafff94c7327aac3b9f2bef84283 Mon Sep 17 00:00:00 2001
From: achu1998 <a1866320@adelaide.edu.au>
Date: Fri, 11 Apr 2025 11:00:46 +0930
Subject: [PATCH] fully-loaded support for the Viewer

---
 src/tiledimage.js | 16 ++++++++++++
 src/viewer.js     | 63 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)

diff --git a/src/tiledimage.js b/src/tiledimage.js
index b350063f..175c492f 100644
--- a/src/tiledimage.js
+++ b/src/tiledimage.js
@@ -257,6 +257,22 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
         return this._fullyLoaded;
     },
 
+    /**
+     * Executes the provided callback when the TiledImage is fully loaded. If already loaded,
+     * schedules the callback asynchronously. Otherwise, attaches a one-time event listener
+     * for the 'fully-loaded-change' event.
+     * @param {Function} callback - Function to execute when loading completes
+     */
+    whenFullyLoaded: function(callback) {
+        if (this.getFullyLoaded()) {
+            setTimeout(callback, 1); // Asynchronous execution
+        } else {
+            this.addOnceHandler('fully-loaded-change', function() {
+                callback.call(this); // Maintain context
+            });
+        }
+    },
+
     // private
     _setFullyLoaded: function(flag) {
         if (flag === this._fullyLoaded) {
diff --git a/src/viewer.js b/src/viewer.js
index 41bed4ae..7d6251c2 100644
--- a/src/viewer.js
+++ b/src/viewer.js
@@ -244,6 +244,8 @@ $.Viewer = function( options ) {
 
     this._lastScrollTime = $.now(); // variable used to help normalize the scroll event speed of different devices
 
+    this._fullyLoaded = false; // variable used to tracks the viewer's aggregate loading state.
+
     //Inherit some behaviors and properties
     $.EventSource.call( this );
 
@@ -364,6 +366,7 @@ $.Viewer = function( options ) {
         viewer: this
     });
 
+    var self = this; // Capture viewer instance
     this.world.addHandler('add-item', function(event) {
         // For backwards compatibility, we maintain the source property
         _this.source = _this.world.getItemAt(0).source;
@@ -373,6 +376,19 @@ $.Viewer = function( options ) {
         if (!_this._updateRequestId) {
             _this._updateRequestId = scheduleUpdate( _this, updateMulti );
         }
+
+        // Attaches a handler to monitor individual TiledImage loading states
+        // propagate aggregate viewer-level fully-loaded status changes.
+        var tiledImage = event.item;
+        tiledImage.addHandler('fully-loaded-change', function() {
+            // Check aggregate loading state across all TiledImages
+            var newFullyLoaded = self.areAllFullyLoaded();
+            // Only trigger event if viewer's loading state has changed
+            if (newFullyLoaded !== self._fullyLoaded) {
+                self._fullyLoaded = newFullyLoaded;
+                self.raiseEvent('fully-loaded-change', { fullyLoaded: newFullyLoaded });
+            }
+        });
     });
 
     this.world.addHandler('remove-item', function(event) {
@@ -561,6 +577,53 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
         return !!this.world.getItemCount();
     },
 
+    /**
+     * Checks whether all TiledImage instances in the viewer's world are fully loaded.
+     * This determines if the entire viewer content is ready for optimal display without partial tile loading.
+     * @returns {Boolean} True if all TiledImages report being fully loaded, false if any image still has pending tiles
+     */
+    areAllFullyLoaded: function() {
+        var tiledImage;
+        var count = this.world.getItemCount();
+
+        // Iterate through all TiledImages in the viewer's world
+        for (var i = 0; i < count; i++) {
+            tiledImage = this.world.getItemAt(i);
+
+            // Return immediately if any image isn't fully loaded
+            if (!tiledImage.getFullyLoaded()) {
+                return false;
+            }
+        }
+        // All images passed the check
+        return true;
+    },
+
+    /**
+     * @function
+     * @returns {Boolean} True if all required tiles are loaded, false otherwise
+     */
+    getFullyLoaded: function() {
+        return this._fullyLoaded;
+    },
+
+    /**
+     * Executes the provided callback when the TiledImage is fully loaded. If already loaded,
+     * schedules the callback asynchronously. Otherwise, attaches a one-time event listener
+     * for the 'fully-loaded-change' event.
+     * @param {Function} callback - Function to execute when loading completes
+     * @memberof OpenSeadragon.Viewer.prototype
+     */
+    whenFullyLoaded: function(callback) {
+        if (this.getFullyLoaded()) {
+            setTimeout(callback, 1); // Asynchronous execution
+        } else {
+            this.addOnceHandler('fully-loaded-change', function() {
+                callback.call(this); // Maintain context
+            });
+        }
+    },
+
     // deprecated
     openDzi: function ( dzi ) {
         $.console.error( "[Viewer.openDzi] this function is deprecated; use Viewer.open() instead." );