1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 *
3 * ***** BEGIN LICENSE BLOCK *****
4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
5 *
6 * The contents of this file are subject to the Mozilla Public License Version
7 * 1.1 (the "License"); you may not use this file except in compliance with
8 * the License. You may obtain a copy of the License at
9 * http://www.mozilla.org/MPL/
10 *
11 * Software distributed under the License is distributed on an "AS IS" basis,
12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
13 * for the specific language governing rights and limitations under the
14 * License.
15 *
16 * The Original Code is the Mozilla browser.
17 *
18 * The Initial Developer of the Original Code is
19 * Netscape Communications, Inc.
20 * Portions created by the Initial Developer are Copyright (C) 1999
21 * the Initial Developer. All Rights Reserved.
22 *
23 * Contributor(s):
24 * Travis Bogard <travis@netscape.com>
25 * Steve Clark <buster@netscape.com>
26 *
27 * Alternatively, the contents of this file may be used under the terms of
28 * either of the GNU General Public License Version 2 or later (the "GPL"),
29 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
30 * in which case the provisions of the GPL or the LGPL are applicable instead
31 * of those above. If you wish to allow use of your version of this file only
32 * under the terms of either the GPL or the LGPL, and not to allow others to
33 * use your version of this file under the terms of the MPL, indicate your
34 * decision by deleting the provisions above and replace them with the notice
35 * and other provisions required by the GPL or the LGPL. If you do not delete
36 * the provisions above, a recipient may use your version of this file under
37 * the terms of any one of the MPL, the GPL or the LGPL.
38 *
39 * ***** END LICENSE BLOCK ***** */
40
41 #include "nsISupports.idl"
42
43 interface nsIDocShellTreeItem;
44
45 /**
46 * The nsIDocShellTreeNode supplies the methods for interacting with children
47 * of a docshell. These are essentially the methods that turn a single docshell
48 * into a docshell tree.
49 */
50
51 /*
52 * Long-term, we probably want to merge this interface into
53 * nsIDocShellTreeItem. Need to eliminate uses of this interface
54 * first.
55 */
56
57 [scriptable, uuid(37f1ab73-f224-44b1-82f0-d2834ab1cec0)]
58 interface nsIDocShellTreeNode : nsISupports
59 {
60 /*
61 The current number of DocShells which are immediate children of the
62 this object.
63 */
64 readonly attribute long childCount;
65
66 /*
67 Add a new child DocShellTreeItem. Adds to the end of the list.
68 Note that this does NOT take a reference to the child. The child stays
69 alive only as long as it's referenced from outside the docshell tree.
70 @throws NS_ERROR_ILLEGAL_VALUE if child corresponds to the same
71 object as this treenode or an ancestor of this treenode
72 @throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
73 */
74 void addChild(in nsIDocShellTreeItem child);
75
76 /*
77 Removes a child DocShellTreeItem.
78 @throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
79 */
80 void removeChild(in nsIDocShellTreeItem child);
81
82 /**
83 * Return the child at the index requested. This is 0-based.
84 *
85 * @throws NS_ERROR_UNEXPECTED if the index is out of range
86 */
87 nsIDocShellTreeItem getChildAt(in long index);
88
89 /*
90 Return the child DocShellTreeItem with the specified name.
91 aName - This is the name of the item that is trying to be found.
92 aRecurse - Is used to tell the function to recurse through children.
93 Note, recursion will only happen through items of the same type.
94 aSameType - If this is set only children of the same type will be returned.
95 aRequestor - This is the docshellTreeItem that is requesting the find. This
96 parameter is used when recursion is being used to avoid searching the same
97 tree again when a child has asked a parent to search for children.
98 aOriginalRequestor - The original treeitem that made the request, if any.
99 This is used to ensure that we don't run into cross-site issues.
100
101 Note the search is depth first when recursing.
102 */
103 nsIDocShellTreeItem findChildWithName(in wstring aName,
104 in boolean aRecurse,
105 in boolean aSameType,
106 in nsIDocShellTreeItem aRequestor,
107 in nsIDocShellTreeItem aOriginalRequestor);
108 };