1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
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();
};
|
