Extraits de code:Scrutateurs de progression

Un article de MDC.

[modifier] Scrutateurs de progression

Les scrutateurs de progression permettent aux extensions de recevoir les notifications des événements associés aux chargements de document dans le navigateur et aux changements de sélection d'onglets. Ils implémentent l'interface nsIWebProgressListener.

Notez que si vous souhaitez seulement exécuter votre code à chaque chargement d'une page, vous pouvez utiliser la méthode plus simple (onPageLoad()).

[modifier] Exemple

1. Créez un objet qui implémente nsIWebProgressListener :

   const STATE_START = Components.interfaces.nsIWebProgressListener.STATE_START;
   const STATE_STOP = Components.interfaces.nsIWebProgressListener.STATE_STOP;
   var myListener =
   {
     QueryInterface: function(aIID)
     {
      if (aIID.equals(Components.interfaces.nsIWebProgressListener) ||
          aIID.equals(Components.interfaces.nsISupportsWeakReference) ||
          aIID.equals(Components.interfaces.nsISupports))
        return this;
      throw Components.results.NS_NOINTERFACE;
     },
   
     onStateChange: function(aProgress, aRequest, aFlag, aStatus)
     {
      if(aFlag & STATE_START)
      {
        // ici lorsque l'événement de chargement est déclenché
      }
      if(aFlag & STATE_STOP)
      {
        // ici lorsque le chargement est terminé
      }
      return 0;
     },
   
     onLocationChange: function(aProgress, aRequest, aURI)
     {
      // ici lorsque l'adresse change, i.e. lorsque l'événement de chargement est confirmé
      // ou lorsque l'utilisateur change d'onglet
      return 0;
     },
   
     // pour les descriptions des fonctions restantes, consultez XulPlanet.com
     onProgressChange: function() {return 0;},
     onStatusChange: function() {return 0;},
     onSecurityChange: function() {return 0;},
     onLinkIconAvailable: function() {return 0;}
   }

2. Attachez le scrutateur de progression à un élément <browser> ou <tabbrowser>, par exemple pour Firefox, placez le code suivant dans un script de chargement (load) de la fenêtre principale :

   gBrowser.addProgressListener(myListener,
     Components.interfaces.nsIWebProgress.NOTIFY_STATE_DOCUMENT);

   Le second argument est filtre d'état qui détermine le type d'événements qui sera reçu. La totalité des six fonctions de l'objet scrutateur doivent être définies même si les filtres sont utilisés.

3. Pensez à appeler un removeProgressListener dans un gestionnaire d'événements unload ou plus tôt.

N'oubliez pas de modifier myListener en un identifiant unique. Pensez également, si vous ajoutez des scrutateurs à l'intérieur d'une fonction, à conserver une référence de votre objet scrutateur qui reste en mémoire (ce qui est nécessaire à l'interface nsISupportsWeakReference). De ce fait, l'objet scrutateur ne devrait jamais être déclaré seulement dans la fonction temporelle.

[modifier] Exemple : notification lorsque la valeur de la barre d'adresse change

Une des questions les plus fréquentes est comment obtenir la notification des changements d'URL dans la barre d'adresse (barre de location). En utilisant le code suivant, vous serez informé lorsque l'utilisateur navigue vers une autre page (en cliquant sur un lien, en utilisant les boutons Reculer/Avancer, en tapant une adresses dans la barre de location, etc.) et également lorsqu'il change d'onglet.

var myExt_urlBarListener = {
  QueryInterface: function(aIID)
  {
   if (aIID.equals(Components.interfaces.nsIWebProgressListener) ||
       aIID.equals(Components.interfaces.nsISupportsWeakReference) ||
       aIID.equals(Components.interfaces.nsISupports))
     return this;
   throw Components.results.NS_NOINTERFACE;
  },

  onLocationChange: function(aProgress, aRequest, aURI)
  {
    myExtension.processNewURL(aURI);
  },

  onStateChange: function() {},
  onProgressChange: function() {},
  onStatusChange: function() {},
  onSecurityChange: function() {},
  onLinkIconAvailable: function() {}
};

var myExtension = {
  oldURL: null,
  
  init: function() {
    // Scrutateur pour les chargements de pages Web
    gBrowser.addProgressListener(myExt_urlBarListener,
        Components.interfaces.nsIWebProgress.NOTIFY_STATE_DOCUMENT);
  },
  
  uninit: function() {
    gBrowser.removeProgressListener(myExt_urlBarListener);
  },

  processNewURL: function(aURI) {
    if (aURI.spec == this.oldURL)
      return;
    
    // maintenant, nous savons que l'url est nouvelle...
    alert(aURI.spec);
    this.oldURL = aURI.spec;
  }
};

window.addEventListener("load", function() {myExtension.init()}, false);
window.addEventListener("unload", function() {myExtension.uninit()}, false);

Note: Si vous utilisez le même scrutateur pour plus d'un onglet (ou fenêtre), utilisez aWebProgress.DOMWindow dans les procédures d'appel pour connaître l'onglet (ou la fenêtre) dont le trigger a changé le statut ou a provoqué un évènement.