michael@0: /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
michael@0:  *
michael@0:  * This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIDocShellTreeOwner;
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * The nsIDocShellTreeItem supplies the methods that are required of any item
michael@0:  * that wishes to be able to live within the docshell tree either as a middle
michael@0:  * node or a leaf. 
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(f897f4af-f67e-4115-9d37-ce09f71122e2)]
michael@0: interface nsIDocShellTreeItem : nsISupports
michael@0: {
michael@0: 	/*
michael@0: 	name of the DocShellTreeItem
michael@0: 	*/
michael@0: 	attribute AString name;
michael@0: 
michael@0:         /**
michael@0:          * Compares the provided name against the item's name and
michael@0:          * returns the appropriate result.
michael@0:          *
michael@0:          * @return <CODE>PR_TRUE</CODE> if names match;
michael@0:          *         <CODE>PR_FALSE</CODE> otherwise.
michael@0:          */
michael@0:         boolean nameEquals(in wstring name);
michael@0: 
michael@0: 	/*
michael@0: 	Definitions for the item types.
michael@0: 	*/
michael@0: 	const long typeChrome=0;            // typeChrome must equal 0
michael@0: 	const long typeContent=1;           // typeContent must equal 1
michael@0: 	const long typeContentWrapper=2;    // typeContentWrapper must equal 2
michael@0: 	const long typeChromeWrapper=3;     // typeChromeWrapper must equal 3
michael@0: 
michael@0: 	const long typeAll=0x7FFFFFFF;
michael@0: 
michael@0: 	/*
michael@0: 	The type this item is.  
michael@0: 	*/
michael@0: 	attribute long itemType;
michael@0: 	[noscript,notxpcom,nostdcall] long ItemType();
michael@0: 
michael@0: 	/*
michael@0: 	Parent DocShell.
michael@0: 	*/
michael@0: 	readonly attribute nsIDocShellTreeItem parent;
michael@0: 
michael@0: 	/*
michael@0: 	This getter returns the same thing parent does however if the parent
michael@0: 	is of a different itemType, or if the parent is an <iframe mozbrowser>
michael@0: 	or <iframe mozapp>, it will instead return nullptr.  This call is a
michael@0: 	convience function for those wishing to not cross the boundaries at
michael@0: 	which item types change.
michael@0: 	*/
michael@0: 	readonly attribute nsIDocShellTreeItem sameTypeParent;
michael@0: 
michael@0: 	/*
michael@0: 	Returns the root DocShellTreeItem.  This is a convience equivalent to 
michael@0: 	getting the parent and its parent until there isn't a parent.
michael@0: 	*/
michael@0: 	readonly attribute nsIDocShellTreeItem rootTreeItem;
michael@0: 
michael@0: 	/*
michael@0: 	Returns the root DocShellTreeItem of the same type.  This is a convience 
michael@0: 	equivalent to getting the parent of the same type and its parent until 
michael@0: 	there isn't a parent.
michael@0: 	*/
michael@0: 	readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem;
michael@0: 
michael@0: 	/*
michael@0: 	Returns the docShellTreeItem with the specified name.  Search order is as 
michael@0: 	follows...
michael@0: 	1.)  Check name of self, if it matches return it.
michael@0: 	2.)  For each immediate child.
michael@0: 		a.) Check name of child and if it matches return it.
michael@0: 		b.)  Ask the child to perform the check
michael@0: 			i.) Do not ask a child if it is the aRequestor
michael@0: 			ii.) Do not ask a child if it is of a different item type.
michael@0: 	3.)  If there is a parent of the same item type ask parent to perform the check
michael@0: 		a.) Do not ask parent if it is the aRequestor
michael@0: 	4.)  If there is a tree owner ask the tree owner to perform the check
michael@0: 		a.)  Do not ask the tree owner if it is the aRequestor
michael@0: 		b.)  This should only be done if there is no parent of the same type.
michael@0: 
michael@0: 	Return the child DocShellTreeItem with the specified name.
michael@0: 	name - This is the name of the item that is trying to be found.
michael@0: 	aRequestor - This is the object that is requesting the find.  This
michael@0: 		parameter is used to identify when the child is asking its parent to find
michael@0: 		a child with the specific name.  The parent uses this parameter to ensure
michael@0: 		a resursive state does not occur by not again asking the requestor to find
michael@0: 		a shell by the specified name.  Inversely the child uses it to ensure it
michael@0: 		does not ask its parent to do the search if its parent is the one that
michael@0: 		asked it to search.  Children also use this to test against the treeOwner;
michael@0: 	aOriginalRequestor - The original treeitem that made the request, if any.
michael@0: 		This is used to ensure that we don't run into cross-site issues.
michael@0: 	*/
michael@0: 	nsIDocShellTreeItem findItemWithName(in wstring name,
michael@0: 	                                     in nsISupports aRequestor,
michael@0: 	                                     in nsIDocShellTreeItem aOriginalRequestor);
michael@0: 
michael@0: 	/*
michael@0: 	The owner of the DocShell Tree.  This interface will be called upon when
michael@0: 	the docshell has things it needs to tell to the owner of the docshell.
michael@0: 	Note that docShell tree ownership does not cross tree types.  Meaning
michael@0: 	setting ownership on a chrome tree does not set ownership on the content 
michael@0: 	sub-trees.  A given tree's boundaries are identified by the type changes.
michael@0: 	Trees of different types may be connected, but should not be traversed
michael@0: 	for things such as ownership.
michael@0: 	
michael@0: 	Note implementers of this interface should NOT effect the lifetime of the 
michael@0: 	parent DocShell by holding this reference as it creates a cycle.  Owners
michael@0: 	when releasing this interface should set the treeOwner to nullptr.
michael@0: 	Implementers of this interface are guaranteed that when treeOwner is
michael@0: 	set that the poitner is valid without having to addref.
michael@0: 	
michael@0: 	Further note however when others try to get the interface it should be 
michael@0: 	addref'd before handing it to them. 
michael@0: 	*/
michael@0: 	readonly attribute nsIDocShellTreeOwner treeOwner;
michael@0: 	[noscript] void setTreeOwner(in nsIDocShellTreeOwner treeOwner);
michael@0: 
michael@0: 	/*
michael@0: 	The current number of DocShells which are immediate children of the 
michael@0: 	this object.
michael@0: 	*/
michael@0: 	readonly attribute long childCount;
michael@0: 
michael@0: 	/*
michael@0: 	Add a new child DocShellTreeItem.  Adds to the end of the list.
michael@0: 	Note that this does NOT take a reference to the child.  The child stays
michael@0: 	alive only as long as it's referenced from outside the docshell tree.
michael@0: 	@throws NS_ERROR_ILLEGAL_VALUE if child corresponds to the same
michael@0: 	        object as this treenode or an ancestor of this treenode
michael@0: 	@throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
michael@0: 	*/
michael@0: 	void addChild(in nsIDocShellTreeItem child);
michael@0: 
michael@0: 	/*
michael@0: 	Removes a child DocShellTreeItem.
michael@0: 	@throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
michael@0: 	*/
michael@0: 	void removeChild(in nsIDocShellTreeItem child);
michael@0: 
michael@0: 	/**
michael@0: 	 * Return the child at the index requested.  This is 0-based.
michael@0: 	 *
michael@0: 	 * @throws NS_ERROR_UNEXPECTED if the index is out of range
michael@0: 	 */
michael@0: 	nsIDocShellTreeItem getChildAt(in long index);
michael@0: 
michael@0: 	/*
michael@0: 	Return the child DocShellTreeItem with the specified name.
michael@0: 	aName - This is the name of the item that is trying to be found.
michael@0: 	aRecurse - Is used to tell the function to recurse through children.
michael@0: 		Note, recursion will only happen through items of the same type.
michael@0: 	aSameType - If this is set only children of the same type will be returned.
michael@0: 	aRequestor - This is the docshellTreeItem that is requesting the find.  This
michael@0: 		parameter is used when recursion is being used to avoid searching the same
michael@0: 		tree again when a child has asked a parent to search for children.
michael@0: 	aOriginalRequestor - The original treeitem that made the request, if any.
michael@0:     	This is used to ensure that we don't run into cross-site issues.
michael@0: 
michael@0: 	Note the search is depth first when recursing.
michael@0: 	*/
michael@0: 	nsIDocShellTreeItem findChildWithName(in wstring aName,
michael@0: 	                                      in boolean aRecurse,
michael@0: 	                                      in boolean aSameType,
michael@0: 	                                      in nsIDocShellTreeItem aRequestor,
michael@0: 	                                      in nsIDocShellTreeItem aOriginalRequestor);
michael@0: };
michael@0: