Os nossos voluntários ainda não traduziram este artigo para Português (Europeu) . Junte-se a nós e ajude-nos a fazer o trabalho!
browser.xul
and navigator.xul
windows; see Note on windows for details.
nsISupports
Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)browser.sessionstore.enabled
must be true
for these calls to be successful. Starting in Firefox 3.5, this preference is no longer used.Method overview
void deleteTabValue(in nsIDOMNode aTab, in AString aKey); |
void deleteWindowValue(in nsIDOMWindow aWindow, in AString aKey); |
nsIDOMNode duplicateTab(in nsIDOMWindow aWindow, in nsIDOMNode aTab); |
nsIDOMNode forgetClosedTab(in nsIDOMWindow aWindow, in unsigned long aIndex); |
nsIDOMNode forgetClosedWindow(in unsigned long aIndex); |
AString getBrowserState(); |
unsigned long getClosedTabCount(in nsIDOMWindow aWindow); |
AString getClosedTabData(in nsIDOMWindow aWindow); |
unsigned long getClosedWindowCount(); |
AString getClosedWindowData(); |
AString getTabState(in nsIDOMNode aTab); |
AString getTabValue(in nsIDOMNode aTab, in AString aKey); |
AString getWindowState(in nsIDOMWindow aWindow); |
AString getWindowValue(in nsIDOMWindow aWindow, in AString aKey); |
void init(in nsIDOMWindow aWindow); |
void persistTabAttribute(in AString aName); |
void restoreLastSession(); |
void setBrowserState(in AString aState); |
void setTabState(in nsIDOMNode aTab, in AString aState); |
void setTabValue(in nsIDOMNode aTab, in AString aKey, in AString aStringValue); |
void setWindowState(in nsIDOMWindow aWindow, in AString aState, in boolean aOverwrite); |
void setWindowValue(in nsIDOMWindow aWindow, in AString aKey, in AString aStringValue); |
nsIDOMNode undoCloseTab(in nsIDOMWindow aWindow, in unsigned long aIndex); |
nsIDOMWindow undoCloseWindow(in unsigned long aIndex); |
Attributes
Attribute | Type | Description |
canRestoreLastSession |
boolean |
Is it possible to restore the previous session. Will always be false when in Private Browsing mode. |
Methods
deleteTabValue()
Deletes a value from a specified tab.
void deleteTabValue( in nsIDOMNode aTab, in AString aKey );
Parameters
-
aTab
- The tab for which to delete the value.
-
aKey
- The key whose value is to be deleted.
Exceptions thrown
This method throws a NS_ERROR_ILLEGAL_VALUE exception if the key doesn't exist.
deleteWindowValue()
Deletes a value from a specified window.
void deleteWindowValue( in nsIDOMWindow aWindow, in AString aKey );
Parameters
-
aWindow
- The window in which to delete the value.
-
aKey
- The key whose value is to be deleted.
duplicateTab()
Duplicates a specified tab as thoroughly as possible.
nsIDOMNode duplicateTab( in nsIDOMWindow aWindow, in nsIDOMNode aTab );
Parameters
-
aWindow
- The window in which the duplicated tab will be created.
-
aTab
- The tab to duplicate (can come from a different window).
Return value
An nsIDOMNode
representing the new tab, the content of which is a duplicate of aTab
.
forgetClosedTab()
nsIDOMNode forgetClosedTab( in nsIDOMWindow aWindow, in unsigned long aIndex );
Parameters
-
aWindow
- Is the browser window associated with the closed tab.
-
aIndex
- Is the index of the closed tab to be removed (FIFO ordered).
Return value
forgetClosedWindow()
nsIDOMNode forgetClosedWindow( in unsigned long aIndex );
Parameters
-
aIndex
- Is the index of the closed window to be removed (FIFO ordered).
Return value
Exceptions thrown
-
NS_ERROR_INVALID_ARG
- When aIndex does not map to a closed window.
getBrowserState()
Returns the current state of all of windows and all of their tabs.
AString getBrowserState();
Parameters
None.
Return value
A JSON string representing the current state of all windows in the web browser.
getClosedTabCount()
Returns the number of restorable tabs for a given window.
unsigned long getClosedTabCount( in nsIDOMWindow aWindow );
Parameters
-
aWindow
- The window whose restorable tab count should be returned.
Return value
The number of restorable tabs in the window.
getClosedTabData()
Returns a list of closed tabs for a specified window.
AString getClosedTabData( in nsIDOMWindow aWindow );
Parameters
-
aWindow
- The browser window whose closed tab list is to be retrieved.
Return value
A JSON string representing the list of closed tabs for the window specified by aWindow
. The list is in last in/first out (LIFO) order, so that the first item in the list is the last tab that was closed.
getClosedWindowCount()
Returns the number of restorable windows.
unsigned long getClosedWindowCount();
Parameters
None.
Return value
The number of restorable windows.
getClosedWindowData()
Returns a list of closed windows.
AString getClosedWindowData();
Parameters
None.
Return value
A JSON string representing the list of closed windows. The list is in last in/first out (LIFO) order, so that the first item in the list is the last window that was closed.
getTabState()
Returns the state of the specified tab.
AString getTabState( in nsIDOMNode aTab );
Parameters
-
aTab
- The tab whose state is to be returned.
Return value
A JSON string representing the state of the specified tab.
getWindowState()
instead.getTabValue()
Returns the value corresponding to a key on a given window.
AString getTabValue( in nsIDOMNode aTab, in AString aKey );
Parameters
-
aTab
- The tab on which to get the value.
-
aKey
- The key whose corresponding value is to be returned.
Return value
The string value that was previously assigned to aKey
using nsISessionStore.setTabValue()
, or an empty string if no value is set for that key.
If the previously saved value was originally a complex data (ie a JavaScript object) it can then be deserialized using JSON.parse
cf. nsISessionStore.setTabValue()
.
getWindowState()
Returns the current state of one specified window in the web browser.
AString getWindowState( in nsIDOMWindow aWindow );
Parameters
-
aWindow
- The browser window whose state is to be returned. See #Note on windows.
Return value
A JSON string representing a session state that contains only the window specified by aWindow
.
If the preference browser.sessionstate.enabled is false when this method is called, then you will get an exception about "aWindows[i] has no properties".
getWindowValue()
Returns the string value associated with a given key for a window.
AString getWindowValue( in nsIDOMWindow aWindow, in AString aKey );
Parameters
-
aWindow
- The window from which the value is to be retrieved.
-
aKey
- The key whose corresponding value is to be retrieved.
Return value
The string value that was previously assigned to aKey
using nsISessionStore.setWindowValue()
, or an empty string if no value is set for that key.
If the previously saved value was originally a complex data (ie a JavaScript object) it can then be deserialized using JSON.parse
cf. nsISessionStore.setWindowValue()
.
init()
Initializes the session store service.
void init( in nsIDOMWindow aWindow );
Parameters
-
aWindow
- The window for which to initialize the service.
persistTabAttribute()
Sets the name of a tab attribute to be saved and restored for all XUL tabs.
void persistTabAttribute( in AString aName );
Parameters
-
aName
- The name of the attribute to be saved and restored for all tabs.
restoreLastSession()
Restore the previous session if possible. This will not overwrite the current session. Instead the previous session will be merged into the current session. Current windows will be reused if they were windows that pinned tabs were previously restored into. New windows will be opened as needed.
canRestoreLastSession
first to avoid thrown errors.void restoreLastSession();
Parameters
None.
setBrowserState()
Sets the current browsing state.
setBrowserState
immediately replaces the current session, restoring the state of the entire application to the state passed in the aState
parameter.void setBrowserState( in AString aState );
Parameters
-
aState
- A JSON string representing the session state to use.
setTabState()
Sets the state of the specified tab.
void setTabState( in nsIDOMNode aTab, in AString aState );
Parameters
-
aTab
- The tab whose state is to be set.
-
aState
-
The JSON string representing the tab state to set on the tab, such as one returned by
getTabState()
.
setTabValue()
Sets the value of a specified key on a tab.
void setTabValue( in nsIDOMNode aTab, in AString aKey, in AString aStringValue );
Parameters
-
aTab
- The tab for which the value is to be set.
-
aKey
- The key whose value is to be set.
-
aStringValue
-
A string to set as the value for the key
aKey
.To assign more complex data (ie JavaScript objects) serialize them using JSON.stringify.
setWindowState()
Sets the state of a single window to a given stored state.
void setWindowState( in nsIDOMWindow aWindow, in AString aState, in boolean aOverwrite );
Parameters
-
aWindow
-
The
nsIDOMWindow
whose state is to be set to the state indicated byaState
. -
aState
- The saved state to apply to the specified window.
-
aOverwrite
-
If this parameter is
true
, all existing tabs are removed and replaced with the tabs in the stateaState
. If it'sfalse
, the tabs inaState
are added to the tabs already in the window.
setWindowValue()
Sets the value corresponding to a given key for a specified window.
void setWindowValue( in nsIDOMWindow aWindow, in AString aKey, in AString aStringValue );
Parameters
-
aWindow
- The browser window for which the value is to be set.
-
aKey
- The key whose value is to be set.
-
aStringValue
-
A string to set as the value for the key
aKey
. To assign more complex data (ie JavaScript objects) serialize them using JSON.stringify.
undoCloseTab()
Reopens a closed tab in a specified window.
nsIDOMNode undoCloseTab( in nsIDOMWindow aWindow, in unsigned long aIndex );
Parameters
-
aWindow
- The browser window in which to reopen a closed tab.
-
aIndex
-
The index number of the closed tab to restore. This should be a value from 0 to one less than the value returned by
getClosedTabCount()
. The list of closed tabs is stored in last in/first out (LIFO) order, so the tab at index 0 is the last one that was closed.
Return value
Prior to Gecko 1.9.1, this method did not return anything. Starting with Gecko 1.9.1, it returns a reference to the reopened tab as an nsIDOMNode
object.
undoCloseWindow()
Reopens a closed window.
nsIDOMWindow undoCloseWindow( in unsigned long aIndex );
Parameters
-
aIndex
-
The index of the window to be restored. This should be a value from 0 to one less than that returned by
getClosedWindowCount()
. The list of closed windows is stored in last in/first out (LIFO) order, so the window at index 0 is the last one that was closed.
Return value
Returns a reference to the reopened window as an nsIDOMWindow
object.
Note on windows
The nsISessionStore
API stores state information for certain windows inside the web brower. These windows are nsIDOMWindow
objects that contain the tabbrowser
that users see as tabs; the document in these windows is browser.xul
.
For many extensions, those that overlay browser.xul
, the appropriate window object for nsISessionStore
is the global object 'window'
.
For JavaScript running in windows other than the one you want to use in nsISessionStore
, you need a nsIDOMWindow
object containing browser.xul
. This will be the outermost or root nsIDOMWindow
in a nsIXULWindow
(the window seen by users as a moveable frame on the display). This kind of DOMWindow object can be obtained from other nsIDOMWindow
objects (like the sidebar window object) by applying the 'mainWindow' statement from Working_with_windows_in_chrome_code. This outermost or root window can also be obtained from the list returned by nsIWindowMediator
; see example #3 in Working_with_windows_in_chrome_code. It can also be obtained from an nsIXULWindow
using
if (xul_win.docShell instanceof nsIInterfaceRequestor) { var win = xul_win.docShell.getInterface(nsIDOMWindow); ...
Note on tabs
The nsISessionStore
APIs referencing nsIDOMNode aTab
require you to get hold of the tab node storing the data. If you you are working in a browser.xul
overlay and want the currently selected tab, it's as simple as gBrowser.selectedTab.
If you just hold a reference to some content document in the overlay's chrome window, here is how you find its corresponding tab:
function tabFromDoc(doc) { var no = gBrowser.getBrowserIndexForDocument(doc); return gBrowser.tabContainer.childNodes[no]; } // example use: Cc['@mozilla.org/browser/sessionstore;1'] .getService(Ci.nsISessionStore) .setTabValue(tabFromDoc(myContentDoc), 'myKey', 'myValue');
See also
- The Session store API article.
nsISessionStartup
- JSON