Progress listeners: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
(→‎Example: removeProgressListener wouldn't hurt)
No edit summary
 
(9 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{extdev}}
Moved to [http://developer.mozilla.org/en/docs/Code_snippets:Progress_Listeners MDC].


==Progress Listeners==
[[Category:Redirects]]
Progress listeners allow extensions to be notified of events associated with documents loading in the browser and with tab switching events. Progress listeners implement the <code>[http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebProgressListener.html nsIWebProgressListener]</code> interface.
 
Note that if you just want to execute your code each time a page loads, you can use an [[On Page Load|an easier method]].
 
==Example==
<ol><li>Create an object which implements <code>nsIWebProgressListener</code>:
<pre>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)
  {
    // This fires when the load event is initiated
  }
  if(aFlag & STATE_STOP)
  {
    // This fires when the load finishes
  }
  return 0;
  },
 
  onLocationChange: function(aProgress, aRequest, aURI)
  {
  // This fires when the location bar changes i.e load event is confirmed
  // or when the user switches tabs
  return 0;
  },
 
  // For definitions of the remaining functions see XulPlanet.com
  onProgressChange: function() {return 0;},
  onStatusChange: function() {return 0;},
  onSecurityChange: function() {return 0;},
  onLinkIconAvailable: function() {return 0;}
}</pre>
</li>
 
<li>Attach the progress listener to a <browser> or a <tabbrowser> element, e.g. for Firefox put the following code in a <code>load</code> listener of a main window:
<pre>gBrowser.addProgressListener(myListener,
  Components.interfaces.nsIWebProgress.NOTIFY_STATE_DOCUMENT);</pre>
 
The second argument is a [http://www.xulplanet.com/references/xpcomref/comps/c_appshellcomponentbrowserstatusfilter1.html status filter] which determines the type of events that will be recieved. All six progress handler functions must be defined, even if filters are used.
</li>
<li>Remember to call <code>removeProgressListener</code> in an <code>unload</code> event handler or earlier.
</li>
</ol>
 
Remember to change <code>myListener</code> to an [[JavaScript coding guidelines|unique identifier]].
 
Also remember that if you're adding listeners inside a function, make sure to have a reference to your listener object that stays in memory (this is due to the required nsISupportsWeakReference interface).
 
== Example: Getting notified when the value in Location Bar changes ==
A commonly asked question is how to get notified whenever the URL in the [[Location Bar]] (also known as address bar) changes. Using the following code, you will get notified when user navigates to another page (by clicking a link, using the back/forward button, by typing an address in the Location Bar, etc.) and also when user switches tabs.
<pre>
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() {
    // Listen for webpage loads
    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;
   
    // now we know the url is new...
    alert(aURI.spec);
    this.oldURL = aURI.spec;
  }
};
 
document.addEventListener("load", function() {myExtension.init()}, false);
document.addEventListener("unload", function() {myExtension.uninit()}, false);
</pre>
 
[[Category:Example code]] [[Category:XPCOM example code]] [[Category:JavaScript example code]]

Latest revision as of 17:57, 30 January 2007

Moved to MDC.