diff options
Diffstat (limited to 'docshell/base/nsIDocShellTreeItem.idl')
| -rw-r--r-- | docshell/base/nsIDocShellTreeItem.idl | 184 |
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(); +}; + |