|
|
(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]]
| |