summaryrefslogtreecommitdiffstats
path: root/docshell/base/nsIDocShellTreeItem.idl
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /docshell/base/nsIDocShellTreeItem.idl
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'docshell/base/nsIDocShellTreeItem.idl')
-rw-r--r--docshell/base/nsIDocShellTreeItem.idl184
1 files changed, 184 insertions, 0 deletions
diff --git a/docshell/base/nsIDocShellTreeItem.idl b/docshell/base/nsIDocShellTreeItem.idl
new file mode 100644
index 000000000..431b16c79
--- /dev/null
+++ b/docshell/base/nsIDocShellTreeItem.idl
@@ -0,0 +1,184 @@
+/* -*- 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 nsIDocShellTreeOwner;
+interface nsIDocument;
+interface nsPIDOMWindowOuter;
+
+
+/**
+ * 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, 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.
+ */
+ attribute long itemType;
+ [noscript,notxpcom,nostdcall] long ItemType();
+
+ /*
+ Parent DocShell.
+ */
+ 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>
+ or <iframe mozapp>, it will instead return nullptr. This call is a
+ convience function for those wishing to not cross the boundaries at
+ which item types change.
+ */
+ 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.
+ */
+ 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.
+ */
+ readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem;
+
+ /*
+ Returns the docShellTreeItem with the specified name. Search order is as
+ follows...
+ 1.) Check name of self, if it matches return it.
+ 2.) For each immediate child.
+ a.) Check name of child and if it matches return it.
+ b.) Ask the child to perform the check
+ i.) Do not ask a child if it is the aRequestor
+ ii.) Do not ask a child if it is of a different item type.
+ 3.) If there is a parent of the same item type ask parent to perform the check
+ a.) Do not ask parent if it is the aRequestor
+ 4.) If there is a tree owner ask the tree owner to perform the check
+ a.) Do not ask the tree owner if it is the aRequestor
+ b.) This should only be done if there is no parent of the same type.
+
+ Return the child DocShellTreeItem with the specified name.
+ name - This is the name of the item that is trying to be found.
+ aRequestor - This is the object that is requesting the find. This
+ parameter is used to identify when the child is asking its parent to find
+ a child with the specific name. The parent uses this parameter to ensure
+ a resursive state does not occur by not again asking the requestor to find
+ a shell by the specified name. Inversely the child uses it to ensure it
+ does not ask its parent to do the search if its parent is the one that
+ asked it to search. Children also use this to test against the treeOwner;
+ aOriginalRequestor - The original treeitem that made the request, if any.
+ This is used to ensure that we don't run into cross-site issues.
+ */
+ nsIDocShellTreeItem findItemWithName(in AString name,
+ in nsISupports aRequestor,
+ in nsIDocShellTreeItem aOriginalRequestor);
+
+ /*
+ 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.
+ */
+ 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.
+ */
+ void addChild(in nsIDocShellTreeItem child);
+
+ /*
+ Removes a child DocShellTreeItem.
+ @throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
+ */
+ void removeChild(in nsIDocShellTreeItem child);
+
+ /**
+ * Return the child at the index requested. This is 0-based.
+ *
+ * @throws NS_ERROR_UNEXPECTED if the index is out of range
+ */
+ nsIDocShellTreeItem getChildAt(in long index);
+
+ /*
+ Return the child DocShellTreeItem with the specified name.
+ aName - This is the name of the item that is trying to be found.
+ aRecurse - Is used to tell the function to recurse through children.
+ Note, recursion will only happen through items of the same type.
+ aSameType - If this is set only children of the same type will be returned.
+ aRequestor - This is the docshellTreeItem that is requesting the find. This
+ parameter is used when recursion is being used to avoid searching the same
+ tree again when a child has asked a parent to search for children.
+ aOriginalRequestor - The original treeitem that made the request, if any.
+ This is used to ensure that we don't run into cross-site issues.
+
+ Note the search is depth first when recursing.
+ */
+ nsIDocShellTreeItem findChildWithName(in AString aName,
+ in boolean aRecurse,
+ in boolean aSameType,
+ in nsIDocShellTreeItem aRequestor,
+ in nsIDocShellTreeItem aOriginalRequestor);
+
+ [noscript,nostdcall,notxpcom] nsIDocument getDocument();
+ [noscript,nostdcall,notxpcom] nsPIDOMWindowOuter getWindow();
+};
+