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 "nsISupports.idl"
   8
   9 interface mozIDOMWindowProxy;
  10 interface nsIDocShellTreeOwner;
  11 interface nsPIDOMWindowOuter;
  12
  13 webidl Document;
  14 webidl BrowsingContext;
  15
  16 /**
  17  * The nsIDocShellTreeItem supplies the methods that are required of any item
  18  * that wishes to be able to live within the docshell tree either as a middle
  19  * node or a leaf.
  20  */
  21
  22 [scriptable, builtinclass, uuid(9b7c586f-9214-480c-a2c4-49b526fff1a6)]
  23 interface nsIDocShellTreeItem : nsISupports
  24 {
  25   /*
  26   name of the DocShellTreeItem
  27   */
  28   attribute AString name;
  29
  30   /**
  31    * Compares the provided name against the item's name and
  32    * returns the appropriate result.
  33    *
  34    * @return <CODE>PR_TRUE</CODE> if names match;
  35    *         <CODE>PR_FALSE</CODE> otherwise.
  36    */
  37   boolean nameEquals(in AString name);
  38
  39   /*
  40   Definitions for the item types.
  41   */
  42   const long typeChrome=0;            // typeChrome must equal 0
  43   const long typeContent=1;           // typeContent must equal 1
  44   const long typeContentWrapper=2;    // typeContentWrapper must equal 2
  45   const long typeChromeWrapper=3;     // typeChromeWrapper must equal 3
  46
  47   const long typeAll=0x7FFFFFFF;
  48
  49   /*
  50   The type this item is.
  51   */
  52   readonly attribute long itemType;
  53   [noscript,notxpcom,nostdcall] long ItemType();
  54
  55   /*
  56   Parent DocShell.
  57
  58   @deprecated: Use `BrowsingContext::GetParent()` instead.
  59   (NOTE: `BrowsingContext::GetParent()` will not cross isolation boundaries)
  60   */
  61   [binaryname(InProcessParent)]
  62   readonly attribute nsIDocShellTreeItem parent;
  63
  64   /*
  65   This getter returns the same thing parent does however if the parent
  66   is of a different itemType, or if the parent is an <iframe mozbrowser>.
  67   It will instead return nullptr.  This call is a convience function for
  68   Ithose wishing to not cross the boundaries at which item types change.
  69
  70   @deprecated: Use `BrowsingContext::GetParent()` instead.
  71   */
  72   [binaryname(InProcessSameTypeParent)]
  73   readonly attribute nsIDocShellTreeItem sameTypeParent;
  74
  75   /*
  76   Returns the root DocShellTreeItem.  This is a convience equivalent to
  77   getting the parent and its parent until there isn't a parent.
  78
  79   @deprecated: Use `BrowsingContext::Top()` instead.
  80   (NOTE: `BrowsingContext::Top()` will not cross isolation boundaries)
  81   */
  82   [binaryname(InProcessRootTreeItem)]
  83   readonly attribute nsIDocShellTreeItem rootTreeItem;
  84
  85   /*
  86   Returns the root DocShellTreeItem of the same type.  This is a convience
  87   equivalent to getting the parent of the same type and its parent until
  88   there isn't a parent.
  89
  90   @deprecated: Use `BrowsingContext::Top()` instead.
  91   */
  92   [binaryname(InProcessSameTypeRootTreeItem)]
  93   readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem;
  94
  95   /*
  96   The owner of the DocShell Tree.  This interface will be called upon when
  97   the docshell has things it needs to tell to the owner of the docshell.
  98   Note that docShell tree ownership does not cross tree types.  Meaning
  99   setting ownership on a chrome tree does not set ownership on the content
 100   sub-trees.  A given tree's boundaries are identified by the type changes.
 101   Trees of different types may be connected, but should not be traversed
 102   for things such as ownership.
 103
 104   Note implementers of this interface should NOT effect the lifetime of the
 105   parent DocShell by holding this reference as it creates a cycle.  Owners
 106   when releasing this interface should set the treeOwner to nullptr.
 107   Implementers of this interface are guaranteed that when treeOwner is
 108   set that the poitner is valid without having to addref.
 109
 110   Further note however when others try to get the interface it should be
 111   addref'd before handing it to them.
 112   */
 113   readonly attribute nsIDocShellTreeOwner treeOwner;
 114   [noscript] void setTreeOwner(in nsIDocShellTreeOwner treeOwner);
 115
 116   /*
 117   The current number of DocShells which are immediate children of the
 118   this object.
 119
 120
 121   @deprecated: Prefer using `BrowsingContext::Children()`, as this count will
 122   not include out-of-process iframes.
 123   */
 124   [binaryname(InProcessChildCount), infallible]
 125   readonly attribute long childCount;
 126
 127   /*
 128   Add a new child DocShellTreeItem.  Adds to the end of the list.
 129   Note that this does NOT take a reference to the child.  The child stays
 130   alive only as long as it's referenced from outside the docshell tree.
 131
 132   @throws NS_ERROR_ILLEGAL_VALUE if child corresponds to the same
 133           object as this treenode or an ancestor of this treenode
 134   @throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
 135   */
 136   [noscript] void addChild(in nsIDocShellTreeItem child);
 137
 138   /*
 139   Removes a child DocShellTreeItem.
 140
 141   @throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
 142   */
 143   [noscript] void removeChild(in nsIDocShellTreeItem child);
 144
 145   /**
 146    * Return the child at the index requested.  This is 0-based.
 147    *
 148    * @deprecated: Prefer using `BrowsingContext::Children()`, as this will not
 149    * include out-of-process iframes.
 150    *
 151    * @throws NS_ERROR_UNEXPECTED if the index is out of range
 152    */
 153   [binaryname(GetInProcessChildAt)]
 154   nsIDocShellTreeItem getChildAt(in long index);
 155
 156   /**
 157    * BrowsingContext associated with the DocShell.
 158    */
 159   [binaryname(BrowsingContextXPCOM)]
 160   readonly attribute BrowsingContext browsingContext;
 161
 162   [noscript,notxpcom,nostdcall] BrowsingContext getBrowsingContext();
 163
 164   /**
 165    * Returns the DOM outer window for the content viewer.
 166    */
 167   readonly attribute mozIDOMWindowProxy domWindow;
 168
 169   [noscript,nostdcall,notxpcom] Document getDocument();
 170   [noscript,nostdcall,notxpcom] nsPIDOMWindowOuter getWindow();
 171 };