You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.


TOC PREV NEXT INDEX

Embedding Gecko API


nsISHistoryListener


This interface must be implemented by an object that wishes to receive notifications about activities in History. A history listener will be notified when pages are added, removed and loaded from session history. A listener to session history can be registered using the interface nsISHistory. This interface is scriptable.

Methods
OnHistoryNewEntry

Notifies a listener when a new document is added to session history. New documents are added to the session history by the docshell when new pages are loaded in a frame or content area.

Syntax:

void nsISHistoryListener::OnHistoryNewEntry(
	in nsIURI aNewURI) 

Parameters:

aNewURI: The URI of the document to be added to session history.

nsresult:

NS_OK if notification was sent out successfully.
OnHistoryGoBack

Notifies a listener when the user presses the 'back' button of the browser OR when the user attempts to go back one page in history through other means, either through scripting or by using nsIWebNavigation.

Syntax:

boolean nsISHistoryListener::OnHistoryGoBack(
	in nsIURI aBackURI) 

Parameters:

aBackURI: The URI of the previous page, which is the page to be loaded.

Returns:

aReturn A boolean flag returned by the listener to indicate if the back operation is to be aborted or continued. If the listener returns TRUE, it indicates that the back operation can be continued. If the listener returns FALSE, then the back operation will be aborted. This is a mechanism by which the listener can control the user's interaction with history.
OnHistoryGoForward

Notifies a listener when the user presses the 'forward' button of the browser OR when the user attempts to go forward one page in history through other means, either through scripting or by using nsIWebNavigation.

Syntax:

boolean nsISHistoryListener::OnHistoryGoForward(
	in nsIURI aForwardURI) 

Parameters:

aForwardURI: The URI of the next page, which is the page to be loaded.

Returns:

aReturn A boolean flag returned by the listener to indicate if the forward operation is to be aborted or continued. If the listener returns TRUE, it indicates that the forward operation can be continued. If the listener returns FALSE, then the forward operation will be aborted. This is a mechanism by which the listener can control the user's interaction with history.
OnHistoryReload

Notifies a listener when the user presses the 'reload' button of the browser OR when the user attempts to reload the current document through other means, either through scripting or by using nsIWebNavigation.

Syntax:

boolean nsISHistoryListener::OnHistoryReload(
	in nsIURI aReloadURI, in unsigned long aReloadFlags) 

Parameters:

aReloadURI: The URI of the current document, which is to be reloaded.
aReloadFlags: Flags that indicate how the document is to be refreshed; from cache, for example, or bypassing the cache and/or proxy server.

Returns:

aReturn A boolean flag returned by the listener to indicate if the reload operation is to be aborted or continued. If the listener returns TRUE, it indicates that the reload operation can be continued. If the listener returns FALSE, then the reload operation will be aborted. This is a mechanism by which the listener can control the user's interaction with history.

See also: nsIWebNavigation

OnHistoryGotoIndex

Notifies a listener when the user visits a page using the 'Go' menu of the browser OR when the user attempts to go to a page at a particular index through other means, like from JavaScript or using nsIWebNavigation.

Syntax:

boolean nsISHistoryListener::OnHistoryGotoIndex(
	in long aIndex, in nsIURI aGotoURI) 

Parameters:

aIndex: The index in history of the document to be loaded.
aGotoURI : The URI of the document to be loaded.

Returns:

aReturn A boolean flag returned by the listener to indicate if the GotoIndex operation is to be aborted or continued. If the listener returns TRUE, it indicates that the GotoIndex operation can be continued. If the listener returns FALSE, then the GotoIndex operation will be aborted. This is a mechanism by which the listener can control the user's interaction with history.
OnHistoryPurge

Notifies a listener when documents are removed from session history. Documents can be removed from session history for various reasons. For example to control the memory usage of the browser, to prevent users from loading documents from history, to erase evidence of prior page loads etc. To purge documents from session history call nsISHistory::PurgeHistory.

Syntax:

boolean nsISHistoryListener::OnHistoryPurge(
	in long aNumEntries) 

Parameters:

aNumEntries: The number of documents to be removed from session history.

Returns:

aReturn A boolean flag returned by the listener to indicate if the purge operation is to be aborted or continued. If the listener returns TRUE, it indicates that the purge operation can be continued. If the listener returns FALSE, then the purge operation will be aborted. This is a mechanism by which the listener can control the user's interaction with history.

Written by:Ellen Evans | Comments, questions, complaints? Bug 143387
TOC PREV NEXT INDEX