docshell/base/nsIDocShellTreeItem.idl

   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 "nsIDocShellTreeNode.idl"
   8
   9 interface nsIDocShellTreeOwner;
  10
  11
  12 /**
  13  * The nsIDocShellTreeItem supplies the methods that are required of any item
  14  * that wishes to be able to live within the docshell tree either as a middle
  15  * node or a leaf.
  16  */
  17
  18 [scriptable, uuid(e35bbb39-985b-4d62-81da-73c330222e5f)]
  19 interface nsIDocShellTreeItem : nsIDocShellTreeNode
  20 {
  21         /*
  22         name of the DocShellTreeItem
  23         */
  24         attribute AString name;
  25
  26         /**
  27          * Compares the provided name against the item's name and
  28          * returns the appropriate result.
  29          *
  30          * @return <CODE>PR_TRUE</CODE> if names match;
  31          *         <CODE>PR_FALSE</CODE> otherwise.
  32          */
  33         boolean nameEquals(in wstring name);
  34
  35         /*
  36         Definitions for the item types.
  37         */
  38         const long typeChrome=0;            // typeChrome must equal 0
  39         const long typeContent=1;           // typeContent must equal 1
  40         const long typeContentWrapper=2;    // typeContentWrapper must equal 2
  41         const long typeChromeWrapper=3;     // typeChromeWrapper must equal 3
  42
  43         const long typeAll=0x7FFFFFFF;
  44
  45         /*
  46         The type this item is.
  47         */
  48         attribute long itemType;
  49
  50         /*
  51         Parent DocShell.
  52         */
  53         readonly attribute nsIDocShellTreeItem parent;
  54
  55         /*
  56         This getter returns the same thing parent does however if the parent
  57         is of a different itemType, or if the parent is an <iframe mozbrowser>
  58         or <iframe mozapp>, it will instead return nullptr.  This call is a
  59         convience function for those wishing to not cross the boundaries at
  60         which item types change.
  61         */
  62         readonly attribute nsIDocShellTreeItem sameTypeParent;
  63
  64         /*
  65         Returns the root DocShellTreeItem.  This is a convience equivalent to
  66         getting the parent and its parent until there isn't a parent.
  67         */
  68         readonly attribute nsIDocShellTreeItem rootTreeItem;
  69
  70         /*
  71         Returns the root DocShellTreeItem of the same type.  This is a convience
  72         equivalent to getting the parent of the same type and its parent until
  73         there isn't a parent.
  74         */
  75         readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem;
  76
  77         /*
  78         Returns the docShellTreeItem with the specified name.  Search order is as
  79         follows...
  80         1.)  Check name of self, if it matches return it.
  81         2.)  For each immediate child.
  82                 a.) Check name of child and if it matches return it.
  83                 b.)  Ask the child to perform the check
  84                         i.) Do not ask a child if it is the aRequestor
  85                         ii.) Do not ask a child if it is of a different item type.
  86         3.)  If there is a parent of the same item type ask parent to perform the check
  87                 a.) Do not ask parent if it is the aRequestor
  88         4.)  If there is a tree owner ask the tree owner to perform the check
  89                 a.)  Do not ask the tree owner if it is the aRequestor
  90                 b.)  This should only be done if there is no parent of the same type.
  91
  92         Return the child DocShellTreeItem with the specified name.
  93         name - This is the name of the item that is trying to be found.
  94         aRequestor - This is the object that is requesting the find.  This
  95                 parameter is used to identify when the child is asking its parent to find
  96                 a child with the specific name.  The parent uses this parameter to ensure
  97                 a resursive state does not occur by not again asking the requestor to find
  98                 a shell by the specified name.  Inversely the child uses it to ensure it
  99                 does not ask its parent to do the search if its parent is the one that
 100                 asked it to search.  Children also use this to test against the treeOwner;
 101         aOriginalRequestor - The original treeitem that made the request, if any.
 102                 This is used to ensure that we don't run into cross-site issues.
 103         */
 104         nsIDocShellTreeItem findItemWithName(in wstring name,
 105                                              in nsISupports aRequestor,
 106                                              in nsIDocShellTreeItem aOriginalRequestor);
 107
 108         /*
 109         The owner of the DocShell Tree.  This interface will be called upon when
 110         the docshell has things it needs to tell to the owner of the docshell.
 111         Note that docShell tree ownership does not cross tree types.  Meaning
 112         setting ownership on a chrome tree does not set ownership on the content
 113         sub-trees.  A given tree's boundaries are identified by the type changes.
 114         Trees of different types may be connected, but should not be traversed
 115         for things such as ownership.
 116
 117         Note implementers of this interface should NOT effect the lifetime of the
 118         parent DocShell by holding this reference as it creates a cycle.  Owners
 119         when releasing this interface should set the treeOwner to nullptr.
 120         Implementers of this interface are guaranteed that when treeOwner is
 121         set that the poitner is valid without having to addref.
 122
 123         Further note however when others try to get the interface it should be
 124         addref'd before handing it to them.
 125         */
 126         readonly attribute nsIDocShellTreeOwner treeOwner;
 127         [noscript] void setTreeOwner(in nsIDocShellTreeOwner treeOwner);
 128 };
 129