Back to index

lightning-sunbird  0.9+nobinonly
nsIDocShellTreeItem.idl
Go to the documentation of this file.
00001 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
00002  *
00003  * ***** BEGIN LICENSE BLOCK *****
00004  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00005  *
00006  * The contents of this file are subject to the Mozilla Public License Version
00007  * 1.1 (the "License"); you may not use this file except in compliance with
00008  * the License. You may obtain a copy of the License at
00009  * http://www.mozilla.org/MPL/
00010  *
00011  * Software distributed under the License is distributed on an "AS IS" basis,
00012  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00013  * for the specific language governing rights and limitations under the
00014  * License.
00015  *
00016  * The Original Code is the Mozilla browser.
00017  *
00018  * The Initial Developer of the Original Code is
00019  * Netscape Communications, Inc.
00020  * Portions created by the Initial Developer are Copyright (C) 1999
00021  * the Initial Developer. All Rights Reserved.
00022  *
00023  * Contributor(s):
00024  *   Travis Bogard <travis@netscape.com>
00025  *
00026  * Alternatively, the contents of this file may be used under the terms of
00027  * either of the GNU General Public License Version 2 or later (the "GPL"),
00028  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00029  * in which case the provisions of the GPL or the LGPL are applicable instead
00030  * of those above. If you wish to allow use of your version of this file only
00031  * under the terms of either the GPL or the LGPL, and not to allow others to
00032  * use your version of this file under the terms of the MPL, indicate your
00033  * decision by deleting the provisions above and replace them with the notice
00034  * and other provisions required by the GPL or the LGPL. If you do not delete
00035  * the provisions above, a recipient may use your version of this file under
00036  * the terms of any one of the MPL, the GPL or the LGPL.
00037  *
00038  * ***** END LICENSE BLOCK ***** */
00039 
00040 #include "nsISupports.idl"
00041 
00042 interface nsIDocShellTreeOwner;
00043 
00044 
00051 [scriptable, uuid(7d935d63-6d2a-4600-afb5-9a4f7d68b825)]
00052 interface nsIDocShellTreeItem : nsISupports
00053 {
00054        /*
00055        name of the DocShellTreeItem
00056        */
00057        attribute wstring name;
00058 
00066         boolean nameEquals(in wstring name);
00067 
00068        /*
00069        Definitions for the item types.
00070        */
00071        const long typeChrome=0;            // typeChrome must equal 0
00072        const long typeContent=1;           // typeContent must equal 1
00073        const long typeContentWrapper=2;    // typeContentWrapper must equal 2
00074        const long typeChromeWrapper=3;     // typeChromeWrapper must equal 3
00075 
00076        const long typeAll=0x7FFFFFFF;
00077 
00078        /*
00079        The type this item is.  
00080        */
00081        attribute long itemType;
00082 
00083        /*
00084        Parent DocShell.
00085        */
00086        readonly attribute nsIDocShellTreeItem parent;
00087 
00088        /*
00089        This is call returns the same thing parent does however if the parent is
00090        of a different itemType, it will instead return nsnull.  This call is a
00091        convience function for those wishing to not cross the boundaries at which
00092        item types change.
00093        */
00094        readonly attribute nsIDocShellTreeItem sameTypeParent;
00095 
00096        /*
00097        Returns the root DocShellTreeItem.  This is a convience equivalent to 
00098        getting the parent and its parent until there isn't a parent.
00099        */
00100        readonly attribute nsIDocShellTreeItem rootTreeItem;
00101 
00102        /*
00103        Returns the root DocShellTreeItem of the same type.  This is a convience 
00104        equivalent to getting the parent of the same type and its parent until 
00105        there isn't a parent.
00106        */
00107        readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem;
00108 
00109        /*
00110        Returns the docShellTreeItem with the specified name.  Search order is as 
00111        follows...
00112        1.)  Check name of self, if it matches return it.
00113        2.)  For each immediate child.
00114               a.) Check name of child and if it matches return it.
00115               b.)  Ask the child to perform the check
00116                      i.) Do not ask a child if it is the aRequestor
00117                      ii.) Do not ask a child if it is of a different item type.
00118        3.)  If there is a parent of the same item type ask parent to perform the check
00119               a.) Do not ask parent if it is the aRequestor
00120        4.)  If there is a tree owner ask the tree owner to perform the check
00121               a.)  Do not ask the tree owner if it is the aRequestor
00122               b.)  This should only be done if there is no parent of the same type.
00123 
00124        Return the child DocShellTreeItem with the specified name.
00125        name - This is the name of the item that is trying to be found.
00126        aRequestor - This is the object that is requesting the find.  This
00127               parameter is used to identify when the child is asking its parent to find
00128               a child with the specific name.  The parent uses this parameter to ensure
00129               a resursive state does not occur by not again asking the requestor to find
00130               a shell by the specified name.  Inversely the child uses it to ensure it
00131               does not ask its parent to do the search if its parent is the one that
00132               asked it to search.  Children also use this to test against the treeOwner;
00133        aOriginalRequestor - The original treeitem that made the request, if any.
00134               This is used to ensure that we don't run into cross-site issues.
00135        */
00136        nsIDocShellTreeItem findItemWithName(in wstring name,
00137                                             in nsISupports aRequestor,
00138                                             in nsIDocShellTreeItem aOriginalRequestor);
00139 
00140        /*
00141        The owner of the DocShell Tree.  This interface will be called upon when
00142        the docshell has things it needs to tell to the owner of the docshell.
00143        Note that docShell tree ownership does not cross tree types.  Meaning
00144        setting ownership on a chrome tree does not set ownership on the content 
00145        sub-trees.  A given tree's boundaries are identified by the type changes.
00146        Trees of different types may be connected, but should not be traversed
00147        for things such as ownership.
00148        
00149        Note implementers of this interface should NOT effect the lifetime of the 
00150        parent DocShell by holding this reference as it creates a cycle.  Owners
00151        when releasing this interface should set the treeOwner to nsnull.
00152        Implementers of this interface are guaranteed that when treeOwner is
00153        set that the poitner is valid without having to addref.
00154        
00155        Further note however when others try to get the interface it should be 
00156        addref'd before handing it to them. 
00157        */
00158        readonly attribute nsIDocShellTreeOwner treeOwner;
00159        [noscript] void setTreeOwner(in nsIDocShellTreeOwner treeOwner);
00160 
00161        /* The offset of yourself in your parent's child list */
00162        attribute long childOffset;
00163 };
00164