summaryrefslogtreecommitdiffstats
path: root/docshell/base/nsIDocShellTreeItem.idl
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docshell/base/nsIDocShellTreeItem.idl171
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..a80373832f
--- /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();
+};