diff options
Diffstat (limited to '')
| -rw-r--r-- | docshell/base/nsIDocShellTreeItem.idl | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/docshell/base/nsIDocShellTreeItem.idl b/docshell/base/nsIDocShellTreeItem.idl new file mode 100644 index 0000000000..ea34cef74b --- /dev/null +++ b/docshell/base/nsIDocShellTreeItem.idl @@ -0,0 +1,171 @@ +/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "nsISupports.idl" + +interface mozIDOMWindowProxy; +interface nsIDocShellTreeOwner; +interface nsPIDOMWindowOuter; + +webidl Document; +webidl BrowsingContext; + +/** + * The nsIDocShellTreeItem supplies the methods that are required of any item + * that wishes to be able to live within the docshell tree either as a middle + * node or a leaf. + */ + +[scriptable, builtinclass, uuid(9b7c586f-9214-480c-a2c4-49b526fff1a6)] +interface nsIDocShellTreeItem : nsISupports +{ + /* + name of the DocShellTreeItem + */ + attribute AString name; + + /** + * Compares the provided name against the item's name and + * returns the appropriate result. + * + * @return <CODE>PR_TRUE</CODE> if names match; + * <CODE>PR_FALSE</CODE> otherwise. + */ + boolean nameEquals(in AString name); + + /* + Definitions for the item types. + */ + const long typeChrome=0; // typeChrome must equal 0 + const long typeContent=1; // typeContent must equal 1 + const long typeContentWrapper=2; // typeContentWrapper must equal 2 + const long typeChromeWrapper=3; // typeChromeWrapper must equal 3 + + const long typeAll=0x7FFFFFFF; + + /* + The type this item is. + */ + readonly attribute long itemType; + [noscript,notxpcom,nostdcall] long ItemType(); + + /* + Parent DocShell. + + @deprecated: Use `BrowsingContext::GetParent()` instead. + (NOTE: `BrowsingContext::GetParent()` will not cross isolation boundaries) + */ + [binaryname(InProcessParent)] + readonly attribute nsIDocShellTreeItem parent; + + /* + This getter returns the same thing parent does however if the parent + is of a different itemType, or if the parent is an <iframe mozbrowser>. + It will instead return nullptr. This call is a convience function for + Ithose wishing to not cross the boundaries at which item types change. + + @deprecated: Use `BrowsingContext::GetParent()` instead. + */ + [binaryname(InProcessSameTypeParent)] + readonly attribute nsIDocShellTreeItem sameTypeParent; + + /* + Returns the root DocShellTreeItem. This is a convience equivalent to + getting the parent and its parent until there isn't a parent. + + @deprecated: Use `BrowsingContext::Top()` instead. + (NOTE: `BrowsingContext::Top()` will not cross isolation boundaries) + */ + [binaryname(InProcessRootTreeItem)] + readonly attribute nsIDocShellTreeItem rootTreeItem; + + /* + Returns the root DocShellTreeItem of the same type. This is a convience + equivalent to getting the parent of the same type and its parent until + there isn't a parent. + + @deprecated: Use `BrowsingContext::Top()` instead. + */ + [binaryname(InProcessSameTypeRootTreeItem)] + readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem; + + /* + The owner of the DocShell Tree. This interface will be called upon when + the docshell has things it needs to tell to the owner of the docshell. + Note that docShell tree ownership does not cross tree types. Meaning + setting ownership on a chrome tree does not set ownership on the content + sub-trees. A given tree's boundaries are identified by the type changes. + Trees of different types may be connected, but should not be traversed + for things such as ownership. + + Note implementers of this interface should NOT effect the lifetime of the + parent DocShell by holding this reference as it creates a cycle. Owners + when releasing this interface should set the treeOwner to nullptr. + Implementers of this interface are guaranteed that when treeOwner is + set that the poitner is valid without having to addref. + + Further note however when others try to get the interface it should be + addref'd before handing it to them. + */ + readonly attribute nsIDocShellTreeOwner treeOwner; + [noscript] void setTreeOwner(in nsIDocShellTreeOwner treeOwner); + + /* + The current number of DocShells which are immediate children of the + this object. + + + @deprecated: Prefer using `BrowsingContext::Children()`, as this count will + not include out-of-process iframes. + */ + [binaryname(InProcessChildCount), infallible] + readonly attribute long childCount; + + /* + Add a new child DocShellTreeItem. Adds to the end of the list. + Note that this does NOT take a reference to the child. The child stays + alive only as long as it's referenced from outside the docshell tree. + + @throws NS_ERROR_ILLEGAL_VALUE if child corresponds to the same + object as this treenode or an ancestor of this treenode + @throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree. + */ + [noscript] void addChild(in nsIDocShellTreeItem child); + + /* + Removes a child DocShellTreeItem. + + @throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree. + */ + [noscript] void removeChild(in nsIDocShellTreeItem child); + + /** + * Return the child at the index requested. This is 0-based. + * + * @deprecated: Prefer using `BrowsingContext::Children()`, as this will not + * include out-of-process iframes. + * + * @throws NS_ERROR_UNEXPECTED if the index is out of range + */ + [binaryname(GetInProcessChildAt)] + nsIDocShellTreeItem getChildAt(in long index); + + /** + * BrowsingContext associated with the DocShell. + */ + [binaryname(BrowsingContextXPCOM)] + readonly attribute BrowsingContext browsingContext; + + [noscript,notxpcom,nostdcall] BrowsingContext getBrowsingContext(); + + /** + * Returns the DOM outer window for the content viewer. + */ + readonly attribute mozIDOMWindowProxy domWindow; + + [noscript,nostdcall,notxpcom] Document getDocument(); + [noscript,nostdcall,notxpcom] nsPIDOMWindowOuter getWindow(); +}; |