docshell/base/nsIDocShellTreeItem.idl

   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  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either of the GNU General Public License Version 2 or later (the "GPL"),
  28  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsIDocShellTreeNode.idl"
  41
  42 interface nsIDocShellTreeOwner;
  43
  44
  45 /**
  46  * The nsIDocShellTreeItem supplies the methods that are required of any item
  47  * that wishes to be able to live within the docshell tree either as a middle
  48  * node or a leaf.
  49  */
  50
  51 [scriptable, uuid(09b54ec1-d98a-49a9-bc95-3219e8b55089)]
  52 interface nsIDocShellTreeItem : nsIDocShellTreeNode
  53 {
  54         /*
  55         name of the DocShellTreeItem
  56         */
  57         attribute wstring name;
  58
  59         /**
  60          * Compares the provided name against the item's name and
  61          * returns the appropriate result.
  62          *
  63          * @return <CODE>PR_TRUE</CODE> if names match;
  64          *         <CODE>PR_FALSE</CODE> otherwise.
  65          */
  66         boolean nameEquals(in wstring name);
  67
  68         /*
  69         Definitions for the item types.
  70         */
  71         const long typeChrome=0;            // typeChrome must equal 0
  72         const long typeContent=1;           // typeContent must equal 1
  73         const long typeContentWrapper=2;    // typeContentWrapper must equal 2
  74         const long typeChromeWrapper=3;     // typeChromeWrapper must equal 3
  75
  76         const long typeAll=0x7FFFFFFF;
  77
  78         /*
  79         The type this item is.
  80         */
  81         attribute long itemType;
  82
  83         /*
  84         Parent DocShell.
  85         */
  86         readonly attribute nsIDocShellTreeItem parent;
  87
  88         /*
  89         This is call returns the same thing parent does however if the parent is
  90         of a different itemType, it will instead return nsnull.  This call is a
  91         convience function for those wishing to not cross the boundaries at which
  92         item types change.
  93         */
  94         readonly attribute nsIDocShellTreeItem sameTypeParent;
  95
  96         /*
  97         Returns the root DocShellTreeItem.  This is a convience equivalent to
  98         getting the parent and its parent until there isn't a parent.
  99         */
 100         readonly attribute nsIDocShellTreeItem rootTreeItem;
 101
 102         /*
 103         Returns the root DocShellTreeItem of the same type.  This is a convience
 104         equivalent to getting the parent of the same type and its parent until
 105         there isn't a parent.
 106         */
 107         readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem;
 108
 109         /*
 110         Returns the docShellTreeItem with the specified name.  Search order is as
 111         follows...
 112         1.)  Check name of self, if it matches return it.
 113         2.)  For each immediate child.
 114                 a.) Check name of child and if it matches return it.
 115                 b.)  Ask the child to perform the check
 116                         i.) Do not ask a child if it is the aRequestor
 117                         ii.) Do not ask a child if it is of a different item type.
 118         3.)  If there is a parent of the same item type ask parent to perform the check
 119                 a.) Do not ask parent if it is the aRequestor
 120         4.)  If there is a tree owner ask the tree owner to perform the check
 121                 a.)  Do not ask the tree owner if it is the aRequestor
 122                 b.)  This should only be done if there is no parent of the same type.
 123
 124         Return the child DocShellTreeItem with the specified name.
 125         name - This is the name of the item that is trying to be found.
 126         aRequestor - This is the object that is requesting the find.  This
 127                 parameter is used to identify when the child is asking its parent to find
 128                 a child with the specific name.  The parent uses this parameter to ensure
 129                 a resursive state does not occur by not again asking the requestor to find
 130                 a shell by the specified name.  Inversely the child uses it to ensure it
 131                 does not ask its parent to do the search if its parent is the one that
 132                 asked it to search.  Children also use this to test against the treeOwner;
 133         aOriginalRequestor - The original treeitem that made the request, if any.
 134                 This is used to ensure that we don't run into cross-site issues.
 135         */
 136         nsIDocShellTreeItem findItemWithName(in wstring name,
 137                                              in nsISupports aRequestor,
 138                                              in nsIDocShellTreeItem aOriginalRequestor);
 139
 140         /*
 141         The owner of the DocShell Tree.  This interface will be called upon when
 142         the docshell has things it needs to tell to the owner of the docshell.
 143         Note that docShell tree ownership does not cross tree types.  Meaning
 144         setting ownership on a chrome tree does not set ownership on the content
 145         sub-trees.  A given tree's boundaries are identified by the type changes.
 146         Trees of different types may be connected, but should not be traversed
 147         for things such as ownership.
 148
 149         Note implementers of this interface should NOT effect the lifetime of the
 150         parent DocShell by holding this reference as it creates a cycle.  Owners
 151         when releasing this interface should set the treeOwner to nsnull.
 152         Implementers of this interface are guaranteed that when treeOwner is
 153         set that the poitner is valid without having to addref.
 154
 155         Further note however when others try to get the interface it should be
 156         addref'd before handing it to them.
 157         */
 158         readonly attribute nsIDocShellTreeOwner treeOwner;
 159         [noscript] void setTreeOwner(in nsIDocShellTreeOwner treeOwner);
 160 };
 161