1/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 *
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6
7#include "nsISupports.idl"
8
9interface nsIDocShellTreeOwner;
10interface nsIDocument;
11interface nsPIDOMWindowOuter;
12
13
14/**
15 * The nsIDocShellTreeItem supplies the methods that are required of any item
16 * that wishes to be able to live within the docshell tree either as a middle
17 * node or a leaf.
18 */
19
20[scriptable, uuid(9b7c586f-9214-480c-a2c4-49b526fff1a6)]
21interface nsIDocShellTreeItem : nsISupports
22{
23	/*
24	name of the DocShellTreeItem
25	*/
26	attribute AString name;
27
28        /**
29         * Compares the provided name against the item's name and
30         * returns the appropriate result.
31         *
32         * @return <CODE>PR_TRUE</CODE> if names match;
33         *         <CODE>PR_FALSE</CODE> otherwise.
34         */
35        boolean nameEquals(in AString name);
36
37	/*
38	Definitions for the item types.
39	*/
40	const long typeChrome=0;            // typeChrome must equal 0
41	const long typeContent=1;           // typeContent must equal 1
42	const long typeContentWrapper=2;    // typeContentWrapper must equal 2
43	const long typeChromeWrapper=3;     // typeChromeWrapper must equal 3
44
45	const long typeAll=0x7FFFFFFF;
46
47	/*
48	The type this item is.
49	*/
50	attribute long itemType;
51	[noscript,notxpcom,nostdcall] long ItemType();
52
53	/*
54	Parent DocShell.
55	*/
56	readonly attribute nsIDocShellTreeItem parent;
57
58	/*
59	This getter returns the same thing parent does however if the parent
60	is of a different itemType, or if the parent is an <iframe mozbrowser>
61	or <iframe mozapp>, it will instead return nullptr.  This call is a
62	convience function for those wishing to not cross the boundaries at
63	which item types change.
64	*/
65	readonly attribute nsIDocShellTreeItem sameTypeParent;
66
67	/*
68	Returns the root DocShellTreeItem.  This is a convience equivalent to
69	getting the parent and its parent until there isn't a parent.
70	*/
71	readonly attribute nsIDocShellTreeItem rootTreeItem;
72
73	/*
74	Returns the root DocShellTreeItem of the same type.  This is a convience
75	equivalent to getting the parent of the same type and its parent until
76	there isn't a parent.
77	*/
78	readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem;
79
80	/*
81	Returns the docShellTreeItem with the specified name.  Search order is as
82	follows...
83	1.)  Check name of self, if it matches return it.
84	2.)  For each immediate child.
85		a.) Check name of child and if it matches return it.
86		b.)  Ask the child to perform the check
87			i.) Do not ask a child if it is the aRequestor
88			ii.) Do not ask a child if it is of a different item type.
89	3.)  If there is a parent of the same item type ask parent to perform the check
90		a.) Do not ask parent if it is the aRequestor
91	4.)  If there is a tree owner ask the tree owner to perform the check
92		a.)  Do not ask the tree owner if it is the aRequestor
93		b.)  This should only be done if there is no parent of the same type.
94
95	Return the child DocShellTreeItem with the specified name.
96	name - This is the name of the item that is trying to be found.
97	aRequestor - This is the object that is requesting the find.  This
98		parameter is used to identify when the child is asking its parent to find
99		a child with the specific name.  The parent uses this parameter to ensure
100		a resursive state does not occur by not again asking the requestor to find
101		a shell by the specified name.  Inversely the child uses it to ensure it
102		does not ask its parent to do the search if its parent is the one that
103		asked it to search.  Children also use this to test against the treeOwner;
104	aOriginalRequestor - The original treeitem that made the request, if any.
105		This is used to ensure that we don't run into cross-site issues.
106	*/
107	nsIDocShellTreeItem findItemWithName(in AString name,
108	                                     in nsISupports aRequestor,
109	                                     in nsIDocShellTreeItem aOriginalRequestor);
110
111	/*
112	The owner of the DocShell Tree.  This interface will be called upon when
113	the docshell has things it needs to tell to the owner of the docshell.
114	Note that docShell tree ownership does not cross tree types.  Meaning
115	setting ownership on a chrome tree does not set ownership on the content
116	sub-trees.  A given tree's boundaries are identified by the type changes.
117	Trees of different types may be connected, but should not be traversed
118	for things such as ownership.
119
120	Note implementers of this interface should NOT effect the lifetime of the
121	parent DocShell by holding this reference as it creates a cycle.  Owners
122	when releasing this interface should set the treeOwner to nullptr.
123	Implementers of this interface are guaranteed that when treeOwner is
124	set that the poitner is valid without having to addref.
125
126	Further note however when others try to get the interface it should be
127	addref'd before handing it to them.
128	*/
129	readonly attribute nsIDocShellTreeOwner treeOwner;
130	[noscript] void setTreeOwner(in nsIDocShellTreeOwner treeOwner);
131
132	/*
133	The current number of DocShells which are immediate children of the
134	this object.
135	*/
136	readonly attribute long childCount;
137
138	/*
139	Add a new child DocShellTreeItem.  Adds to the end of the list.
140	Note that this does NOT take a reference to the child.  The child stays
141	alive only as long as it's referenced from outside the docshell tree.
142	@throws NS_ERROR_ILLEGAL_VALUE if child corresponds to the same
143	        object as this treenode or an ancestor of this treenode
144	@throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
145	*/
146	void addChild(in nsIDocShellTreeItem child);
147
148	/*
149	Removes a child DocShellTreeItem.
150	@throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
151	*/
152	void removeChild(in nsIDocShellTreeItem child);
153
154	/**
155	 * Return the child at the index requested.  This is 0-based.
156	 *
157	 * @throws NS_ERROR_UNEXPECTED if the index is out of range
158	 */
159	nsIDocShellTreeItem getChildAt(in long index);
160
161	/*
162	Return the child DocShellTreeItem with the specified name.
163	aName - This is the name of the item that is trying to be found.
164	aRecurse - Is used to tell the function to recurse through children.
165		Note, recursion will only happen through items of the same type.
166	aSameType - If this is set only children of the same type will be returned.
167	aRequestor - This is the docshellTreeItem that is requesting the find.  This
168		parameter is used when recursion is being used to avoid searching the same
169		tree again when a child has asked a parent to search for children.
170	aOriginalRequestor - The original treeitem that made the request, if any.
171    	This is used to ensure that we don't run into cross-site issues.
172
173	Note the search is depth first when recursing.
174	*/
175	nsIDocShellTreeItem findChildWithName(in AString aName,
176	                                      in boolean aRecurse,
177	                                      in boolean aSameType,
178	                                      in nsIDocShellTreeItem aRequestor,
179	                                      in nsIDocShellTreeItem aOriginalRequestor);
180
181  [noscript,nostdcall,notxpcom] nsIDocument getDocument();
182  [noscript,nostdcall,notxpcom] nsPIDOMWindowOuter getWindow();
183};
184
185