Nos bénévoles n'ont pas encore traduit cet article en Français. Aidez-nous à réaliser cette tâche !
nsISupports
Last changed in Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9)Implemented by @mozilla.org/docshell;1. Do not create an instance directly. Instead, retrieve an nsIDocShell
from a browser or other document container element. Note that out-of-process browsers do not have an nsIDocShell
; instead you can access the nsIDocShell
object from a frame script.
Method overview
void addSessionStorage(in nsIPrincipal principal, in nsIDOMStorage storage); |
void addState(in nsIVariant aData, in DOMString aTitle, in DOMString aURL, in boolean aReplace); |
void beginRestore(in nsIContentViewer viewer, in boolean top); |
void createAboutBlankContentViewer(in nsIPrincipal aPrincipal); |
void createLoadInfo(out nsIDocShellLoadInfo loadInfo); |
void DetachEditorFromWindow(); Violates the XPCOM interface guidelines |
void finishRestore(); |
void firePageHideNotification(in boolean isUnload); Native code only! |
void fireUnloadNotification(); Native code only! Obsolete since Gecko 1.8 |
nsISimpleEnumerator getDocShellEnumerator(in long aItemType, in long aDirection); |
nsIDOMStorage getSessionStorageForPrincipal(in nsIPrincipal principal, in DOMString documentURI, in boolean create); |
nsIDOMStorage getSessionStorageForURI(in nsIURI uri, in DOMString documentURI); |
void historyPurged(in long numEntries); |
void internalLoad(in nsIURI aURI, in nsIURI aReferrer, in nsISupports aOwner, in PRUint32 aFlags, in wstring aWindowTarget, in string aTypeHint, in nsIInputStream aPostDataStream, in nsIInputStream aHeadersStream, in unsigned long aLoadFlags, in nsISHEntry aSHEntry, in boolean firstParty, out nsIDocShell aDocShell, out nsIRequest aRequest); Native code only! |
boolean isBeingDestroyed(); |
void loadStream(in nsIInputStream aStream, in nsIURI aURI, in ACString aContentType, in ACString aContentCharset, in nsIDocShellLoadInfo aLoadInfo); Native code only! |
void loadURI(in nsIURI uri, in nsIDocShellLoadInfo loadInfo, in unsigned long aLoadFlags, in boolean firstParty); Native code only! |
void prepareForNewContentModel(); |
void resumeRefreshURIs(); |
void setChildOffset(in unsigned long offset); Native code only! |
void setCurrentURI(in nsIURI aURI); |
void suspendRefreshURIs(); |
void tabToTreeOwner(in boolean forward, out boolean tookFocus); |
Attributes
Attribute | Type | Description |
allowAuth |
boolean |
Certain dochshells (like the message pane) should not throw up auth dialogs because it can act as a password trojan. |
allowDNSPrefetch |
boolean |
Attribute that determines whether DNS prefetch is allowed for this subtree of the docshell tree. Defaults to true . Setting this will make it take effect starting with the next document loaded in the docshell. |
allowImages |
boolean |
Attribute stating whether or not images should be loaded. |
allowJavascript |
boolean |
Whether to allow Javascript execution. |
allowMedia |
boolean |
Attribute stating whether or not media (audio/video) should be loaded. Requires Gecko 24 |
allowMetaRedirects |
boolean |
Attribute stating if refresh based redirects can be allowed. |
allowPlugins |
boolean |
Whether to allow plugin execution. |
allowSubframes |
boolean |
Attribute stating if it should allow subframes (framesets/iframes) or not. |
allowWindowControl |
boolean |
Specifies whether or not content is allowed to control the window (that is, to resize or move the window). Default is true , which lets content control the window. |
appType |
unsigned long |
The type of application that created this window. Types are defined in Constants. |
busyFlags |
unsigned long |
Current busy state for DocShell. Valid states are defined in Constants. Read only. |
canExecuteScripts |
boolean |
Whether this docshell can execute scripts based on its hierarchy. The rule of thumb here is that we disable js if this docshell or any of its parents disallow scripting, unless the only reason for js being disabled in this docshell is a parent docshell having a document that is in design mode. In that case, we explicitly allow scripting on the current docshell. Read only. |
canvasHasFocus |
boolean |
Tells the docshell whether the canvas should have focus. Called by the focus manager when the user tabs to the frame rather than an element. Obsolete since Gecko 1.9.2 |
channelIsUnsafe |
boolean |
Find out if the currently loaded document came from a suspicious channel (such as a JAR channel where the server-returned content type is not a known JAR type). Read only. |
charset |
string |
The converter to use when reading the document's data. In Mozilla code, all text is encoded as Unicode. When reading a document, a converter is used to translate the text from its original format into Unicode. This attribute lets you:
Reading this value reports the encoding that was used when loading the data into the document. Setting this attribute overrides the encoding; however, to update the DOM or display of the content, you need have the data reparsed. Overriding the character set also sets the fallback encoding for the container frame. Note: Prior to Gecko 12.0, this attribute was part of a separate |
chromeEventHandler |
|
Events generated in the frame bubble up to its chromeEventHandler . In the case of a content frame or subframe this is the containing chrome frame. In the case of a chrome frame this is the same as the frame element. This attribute allows chrome to tie in to handle DOM events that may be of interest to chrome. |
contentViewer |
|
Content Viewer that is currently loaded for this DocShell. This may change as the underlying content changes. Read only. |
currentDocumentChannel |
|
Gets the channel for the currently loaded document, if any. For a new document load, this will be the channel of the previous document until after OnLocationChange fires. Read only. |
documentCharsetInfo |
|
The document character set info. This is used by a load to determine priorities for charset detection and so on. Obsolete since Gecko 12.0 Note: The properties of the old |
eldestPresShell |
|
Presentation shell for the oldest document, if this docshell is currently transitioning between documents. Read only. Native code only! |
forcedCharset |
nsIAtom |
A character set to override the page's default character set while processing; this is tried before using any other character set during page loads. Note: Prior to Gecko 12.0, this attribute was part of a separate |
hasFocus |
boolean |
Tells the DocShell that it now has focus or has lost focus. Obsolete since Gecko 1.9.2 |
historyID |
unsigned long long |
The ID of the docshell in the session history. Read only. |
isActive |
boolean |
Indicates whether or not the DocShell is currently active. An active DocShell is one that is currently visible, which means it's not a good candidate for optimizations such as image frame discarding. DocShells are active if this is Note: Starting in Gecko 8.0, |
isAppTab |
boolean |
Sets whether a docshell is an app tab. An app tab docshell may behave differently than a non-app tab docshell in some cases, such as when handling link clicks. Docshells are not app tabs unless told otherwise. |
isExecutingOnLoadHandler |
boolean |
Returns true if the docshell is currently executing the onLoad Handler. Read only. |
isInUnload |
boolean |
Find out whether the docshell is currently in the middle of a page transition (after the onunload event has fired, but before the new document has been set up) Read only. |
isOffScreenBrowser |
boolean |
If true , this docshell is not visible in the traditional sense, but is being actively rendered to the screen (such as by being painted to a canvas), and should be treated accordingly. |
layoutHistoryState |
|
|
loadedTransIndex |
long |
Keeps track of the previous SHTransaction index and the current SHTransaction index at the time that the doc shell begins to load. Used for ContentViewer eviction. Read only. |
loadType |
unsigned long |
Load type for the document. Valid states are defined in Constants. Note that nsIDocShell may use other states internally so you should check for the specific state bit. |
marginHeight |
long |
The value of the marginheight attribute on the frame element, or negative if it was not set. |
marginWidth |
long |
The value of the marginwidth attribute on the frame element, or negative if it was not set. |
parentCharset |
nsIAtom |
Indicates the DocShell's parent document's character set. Note: Prior to Gecko 12.0, this attribute was part of a separate |
parentCharsetSource |
PRInt32 |
Indicates the source from which the character set being used was obtained. Higher numbers override lower ones. See Character set source constants for defined values. Note: Prior to Gecko 12.0, this attribute was part of a separate |
parentURIContentListener |
|
URI content listener parent. This is not refcounted and is assumed to be nulled out by the parent when the parent is going away. Obsolete since Gecko 1.8 |
presContext |
|
Presentation context for the currently loaded document. This may be null . Read only. Native code only! |
presShell |
|
Presentation shell for the currently loaded document. This may be null . Read only. Native code only! |
previousTransIndex |
long |
Keeps track of the previous SHTransaction index and the current SHTransaction index at the time that the doc shell begins to load. Used for ContentViewer eviction. Read only. |
printPreview |
|
If the current content viewer is not initialized for print preview, it is replaced with one which is and to which an about:blank document is loaded. Read only. |
restoringDocument |
boolean |
Track whether we're currently restoring a document presentation. Read only. |
securityUI |
|
The SecureBrowserUI object for this docshell. This is set by browser or nsWebBrowser for their root docshell. |
shouldSaveLayoutState |
boolean |
Indicates whether the current page can be cached. Read only. |
useErrorPages |
boolean |
Attribute to access whether error pages are enabled. |
zoom |
float |
Set/Get the document scale factor. When setting this attribute, a NS_ERROR_NOT_IMPLEMENTED error may be returned by implementations not supporting zoom. Implementations not supporting zoom should return 1.0 all the time for the Get operation. 1.0 by the way is the default of zoom. This means 100% of normal scaling or in other words normal size no zoom. |
Constants
Constant | Value | Description |
INTERNAL_LOAD_FLAGS_NONE |
0x0 |
Used as a placeholder when you don't want to explicitly specify flags. |
INTERNAL_LOAD_FLAGS_INHERIT_OWNER |
0x1 |
Used to indicate that it may be safe to inherit the owner of a javascript: or data: URL from the existing document. |
INTERNAL_LOAD_FLAGS_DONT_SEND_REFERRER |
0x2 |
Used to indicate that the load was caused by a meta refresh and the current document URI shouldn't be sent as the HTTP referrer. |
INTERNAL_LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP |
0x4 |
Used to indicate that LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP was passed as one of the flags to loadURI() . |
INTERNAL_LOAD_FLAGS_FIRST_LOAD |
0x8 |
This flag marks the first load in this object. See nsIWebNavigation .LOAD_FLAGS_FIRST_LOAD . |
INTERNAL_LOAD_FLAGS_BYPASS_CLASSIFIER |
0x10 |
Used to indicate that LOAD_FLAGS_BYPASS_CLASSIFIER was passed as one of the flags to loadURI() . |
INTERNAL_LOAD_FLAGS_FORCE_ALLOW_COOKIES |
0x20 |
Used to indicate that LOAD_FLAGS_FORCE_ALLOW_COOKIES was passed as one of the flags to loadURI() . |
ENUMERATE_FORWARDS |
0 |
Used by getDocShellEnumerator() to determine the direction of the enumeration. |
ENUMERATE_BACKWARDS |
1 |
Used by getDocShellEnumerator() to determine the direction of the enumeration. |
APP_TYPE_UNKNOWN |
0 |
This is the default value of the appType attribute. |
APP_TYPE_MAIL |
1 |
This is the value of the appType attribute used by Thunderbird and SeaMonkey to indicate that email messages are displayed in this window. |
APP_TYPE_EDITOR |
2 |
This is the value of the appType attribute used by Thunderbird and SeaMonkey to indicate that email messages or web pages are composed in this window. |
BUSY_FLAGS_NONE |
0 |
Returned by the busyFlags attribute when the nsIDocShell is not loading a document. |
BUSY_FLAGS_BUSY |
1 |
Returned by the busyFlags attribute when the nsIDocShell is loading a document from the network. |
BUSY_FLAGS_BEFORE_PAGE_LOAD |
2 |
Returned by the busyFlags attribute when the nsIDocShell has started loading a document from the network, but no data has been received yet. |
BUSY_FLAGS_PAGE_LOADING |
4 |
Returned by the busyFlags attribute when the nsIDocShell is receiving data from the network. |
LOAD_CMD_NORMAL |
0x1 |
Returned by the loadType attribute for normal loads. |
LOAD_CMD_RELOAD |
0x2 |
Returned by the loadType attribute for reloads. |
LOAD_CMD_HISTORY |
0x4 |
Returned by the loadType attribute for history navigation. |
LOAD_CMD_PUSHSTATE |
0x8 |
Returned by the loadType attribute when the page has used history.pushState() |
Character set source constants
These constants are not exposed to script. They are used internally as values for the parentCharsetSource
attribute.
Constant | Value | Description |
kCharsetUninitialized |
0 | The character set has not yet been initialized. |
kCharsetFromWeakDocTypeDefault |
1 | |
kCharsetFromUserDefault |
2 | The user's default character set is being used. |
kCharsetFromDocTypeDefault |
3 | The character set has been inferred from the doctype. All values from here upward are confident enough to be used for XMLHttpRequest . |
kCharsetFromCache |
4 | The character set has been retrieved from the cache. |
kCharsetFromParentFrame |
5 | The parent frame's character set is being used. |
kCharsetFromAutoDetection |
6 | The character set was automatically detected. |
kCharsetFromHintPrevDoc |
7 | The character set was hinted by the previous document. |
kCharsetFromMetaPrescan |
8 | Values from this one downward are HTML5 tentative. |
kCharsetFromMetaTag |
9 | Values from this one upward are HTML5 confident. |
kCharsetFromIrreversibleAutoDetection |
10 | |
kCharsetFromByteOrderMark |
11 | The character set was determined from a byte order mark in the content. |
kCharsetFromChannel |
12 | The nsIChannel specified the character set. |
kCharsetFromOtherComponent |
13 | |
kCharsetFromParentForced |
14 | The parent's character set was forced onto this content; all descendents will have this character set forced onto it. |
kCharsetFromUserForced |
15 | The user specified a character set to force onto this content; all descendents will have this character set forced onto it. |
kCharsetFromPreviousLoading |
Methods
addSessionStorage()
Add a WebApps session storage object to the docshell.
void addSessionStorage( in nsIPrincipal principal, in nsIDOMStorage storage );
Parameters
-
principal
- The principal to use for the new storage object.
-
storage
- The storage object to add.
addState()
Do either a history.pushState() or history.replaceState() operation, depending on the value of aReplace.
void addState( in nsIVariant aData, in DOMString aTitle, in DOMString aURL, in boolean aReplace );
Parameters
-
aData
-
The state object to pass to the
popstate
event. It must be possible to serialise this in less than 640k characters. -
aTitle
- Gecko currently ignores this parameter.
-
aURL
- The URL associated with the new history entry. For instance, if the user tries to reload the page, then this is the URL that will be reloaded.
-
aReplace
- Whether to modify the current history entry instead of creating a new one.
beginRestore()
Begin firing WebProgressListener notifications for restoring a page presentation. This method will post an event to complete the simulated load after returning to the event loop.
void beginRestore( in nsIContentViewer viewer, in boolean top );
Parameters
-
viewer
-
The content viewer whose document we are starting to load. If
null
, it defaults to the docshell's current content viewer, creating one if necessary. -
top
-
Should be
true
for the toplevel docshell that is being restored; it will be set tofalse
when this method is called for child docshells.
createAboutBlankContentViewer()
Create a new about:blank document and content viewer.
void createAboutBlankContentViewer( in nsIPrincipal aPrincipal );
Parameters
-
aPrincipal
- The principal to use for the new document.
createLoadInfo()
Creates a DocShellLoadInfo object that you can manipulate and then pass to loadURI()
.
void createLoadInfo( out nsIDocShellLoadInfo loadInfo );
Parameters
-
loadInfo
-
The new
nsIDocShellLoadInfo
object.
DetachEditorFromWindow()
Disconnects this docshell's editor from its window, and stores the editor data in the open document's session history entry. This should be called only during page transitions.
void DetachEditorFromWindow();
Parameters
None.
finishRestore()
Finish firing WebProgressListener notifications and DOM events for restoring a page presentation. This should only be called via beginRestore()
.
void finishRestore();
Parameters
None.
firePageHideNotification
Notify the associated content viewer and all child docshells that they are about to be hidden. If isUnload
is true
, then the document is being unloaded as well.
void firePageHideNotification( in boolean isUnload );
Parameters
-
isUnload
-
If
true
, fire the unload event in addition to the pagehide event.
fireUnloadNotification
Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.
Notify the associated content viewer and all child docshells that they are about to be unloaded.
void fireUnloadNotification();
Parameters
None.
getDocShellEnumerator()
Get an enumerator over this docShell and its children.
nsISimpleEnumerator getDocShellEnumerator( in long aItemType, in long aDirection );
Parameters
-
aItemType
-
Only include docShells of this type, or if typeAll, include all child shells. Uses types from
nsIDocShellTreeItem
. -
aDirection
- Whether to enumerate forwards or backwards.
Return value
An enumerator over this docShell and its children.
getSessionStorageForPrincipal()
Retrieves the session storage object for the supplied principal.
nsIDOMStorage getSessionStorageForPrincipal( in nsIPrincipal principal, in DOMString documentURI, in boolean create );
Parameters
-
principal
- The principal of the storage object to retrieve.
-
documentURI
-
If a new storage object needs to be created, it will be created with a reference to this
document.documentURI
in itsStorageEvent
. -
create
-
If this is
true
, a new session storage object will be created.
Return value
The new or existing session storage object, if any.
getSessionStorageForURI()
Retrieves the session storage object for the supplied domain. If session storage object does not already exist, a new one will be created.
nsIDOMStorage getSessionStorageForURI( in nsIURI uri, in DOMString documentURI );
Parameters
-
uri
- The domain of the storage object to retrieve.
-
documentURI
-
If a new storage object needs to be created, it will be created with a reference to this
document.documentURI
in itsStorageEvent
.
Return value
The session storage object for the supplied domain.
historyPurged()
Notification that entries have been removed from the beginning of a nsSHistory which has this as its rootDocShell.
void historyPurged( in long numEntries );
Parameters
-
numEntries
- The number of entries removed.
internalLoad
Loads the given URI. This method is identical to loadURI()
except that its parameter list is broken out instead of being packaged inside of an nsIDocShellLoadInfo
object.
void internalLoad( in nsIURI aURI, in nsIURI aReferrer, in nsISupports aOwner, in PRUint32 aFlags, in wstring aWindowTarget, in string aTypeHint, in nsIInputStream aPostDataStream, in nsIInputStream aHeadersStream, in unsigned long aLoadFlags, in nsISHEntry aSHEntry, in boolean firstParty, out nsIDocShell aDocShell, out nsIRequest aRequest );
Parameters
-
aURI
- The URI to load.
-
aReferrer
- Referring URI.
-
aOwner
- Owner (security principal)
-
aFlags
- A combination of the internal load flags as detailed in the constants secion.
-
aWindowTarget
- Window target for the load.
-
aTypeHint
-
A hint as to the content-type of the resulting data. May be
null
or empty if no hint. -
aPostDataStream
- Post data stream (if POSTing)
-
aHeadersStream
- Stream containing "extra" request headers.
-
aLoadFlags
-
Flags to modify load behaviour. Flags are defined in
nsIWebNavigation
. -
aSHEntry
- Active Session History entry (if loading from SH)
-
firstParty
-
true
if this is the master top-level document. -
aDocShell
- If the load was succesfully initiated, this receives the nsIDocShell that actually performed the load.
-
aRequest
- The new channel created for the load.
isBeingDestroyed()
boolean isBeingDestroyed();
Parameters
None.
Return value
Returns true
if the docshell is being destroyed, false
otherwise.
loadStream
Loads a given stream. This will give priority to loading the requested stream in the object implementing this interface. If it can not be loaded here however, the URL dispatched will go through its normal process of content loading.
void loadStream( in nsIInputStream aStream, in nsIURI aURI, in ACString aContentType, in ACString aContentCharset, in nsIDocShellLoadInfo aLoadInfo );
Parameters
-
aStream
- The input stream that provides access to the data to be loaded. This must be a blocking, threadsafe stream implementation.
-
aURI
-
The URI representing the stream, or
null
. -
aContentType
- The type (MIME) of data being loaded (empty if unknown).
-
aContentCharset
- The charset of the data being loaded (empty if unknown).
-
aLoadInfo
-
This is the extended load info for this load. This most often will be
null
, but if you need to do additional setup for this load you can get aloadInfo
object by callingcreateLoadInfo()
. Once you have this object you can set the needed properties on it and then pass it toloadStream
.
loadURI
Loads a given URI. This will give priority to loading the requested URI in the object implementing this interface. If it can not be loaded here however, the URL dispatcher will go through its normal process of content loading.
void loadURI( in nsIURI uri, in nsIDocShellLoadInfo loadInfo, in unsigned long aLoadFlags, in boolean firstParty );
Parameters
-
uri
- The URI to load.
-
loadInfo
-
This is the extended load info for this load. This most often will be
null
, but if you need to do additional setup for this load you can get aloadInfo
object by callingcreateLoadInfo()
. Once you have this object you can set the needed properties on it and then pass it toloadURI
. -
aLoadFlags
-
Flags to modify load behaviour. Flags are defined in
nsIWebNavigation
. Note that using flags outside LOAD_FLAGS_MASK is only allowed if passing in a non-null
loadInfo. And even some of those might not be allowed. Use at your own risk. -
firstParty
-
true
if this is the master top-level document.
prepareForNewContentModel()
Reset state to a new content model within the current document and the document viewer. Called by the document before initiating an out of band document.write()
.
void prepareForNewContentModel();
Parameters
None.
resumeRefreshURIs()
Restart the XPCOM timers for each meta-refresh URI in this docshell, and this docshell's children, recursively. If the timers are already running, this has no effect.
void resumeRefreshURIs();
Parameters
None.
setChildOffset
Set the offset of this child in its container.
void setChildOffset( in unsigned long offset );
Parameters
-
offset
- The offset of this nsIDocShell within its parent. Used to restore session history for frames.
setCurrentURI()
For editors and suchlike who wish to change the URI associated with the document. Note if you want to get the current URI, use the read-only property on nsIWebNavigation
.
void setCurrentURI( in nsIURI aURI );
Parameters
-
aURI
- The URI to load.
suspendRefreshURIs()
Cancel the XPCOM timers for each meta-refresh URI in this docshell, and this docshell's children, recursively. The meta-refresh timers can be restarted using resumeRefreshURIs()
. If the timers are already suspended, this has no effect.
void suspendRefreshURIs();
Parameters
None.
tabToTreeOwner()
Tells the docshell to offer focus to its tree owner. This is currently only necessary for embedding chrome.
void tabToTreeOwner( in boolean forward, out boolean tookFocus );
Parameters
-
forward
- Whether to tab forwards or backwards.
-
tookFocus
- Whether or not an element was successfully focused.