"Fossies" - the Fresh Open Source Software Archive

Member "firefox-69.0.1/docshell/base/nsIDocShellTreeItem.idl" (17 Sep 2019, 7573 Bytes) of package /linux/www/firefox-69.0.1.source.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) IDL source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes reports for "nsIDocShellTreeItem.idl": 60.7.2_vs_68.0 or 67.0.4_vs_68.0.

    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 
   15 /**
   16  * The nsIDocShellTreeItem supplies the methods that are required of any item
   17  * that wishes to be able to live within the docshell tree either as a middle
   18  * node or a leaf.
   19  */
   20 
   21 [scriptable, builtinclass, uuid(9b7c586f-9214-480c-a2c4-49b526fff1a6)]
   22 interface nsIDocShellTreeItem : nsISupports
   23 {
   24     /*
   25     name of the DocShellTreeItem
   26     */
   27     attribute AString name;
   28 
   29         /**
   30          * Compares the provided name against the item's name and
   31          * returns the appropriate result.
   32          *
   33          * @return <CODE>PR_TRUE</CODE> if names match;
   34          *         <CODE>PR_FALSE</CODE> otherwise.
   35          */
   36         boolean nameEquals(in AString name);
   37 
   38     /*
   39     Definitions for the item types.
   40     */
   41     const long typeChrome=0;            // typeChrome must equal 0
   42     const long typeContent=1;           // typeContent must equal 1
   43     const long typeContentWrapper=2;    // typeContentWrapper must equal 2
   44     const long typeChromeWrapper=3;     // typeChromeWrapper must equal 3
   45 
   46     const long typeAll=0x7FFFFFFF;
   47 
   48     /*
   49     The type this item is.
   50     */
   51     readonly attribute long itemType;
   52     [noscript,notxpcom,nostdcall] long ItemType();
   53 
   54     /*
   55     Parent DocShell.
   56     */
   57     readonly attribute nsIDocShellTreeItem parent;
   58 
   59     /*
   60     This getter returns the same thing parent does however if the parent
   61     is of a different itemType, or if the parent is an <iframe mozbrowser>.
   62     It will instead return nullptr.  This call is a convience function for
   63     Ithose wishing to not cross the boundaries at which item types change.
   64     */
   65     readonly attribute nsIDocShellTreeItem sameTypeParent;
   66 
   67     /*
   68     Returns the root DocShellTreeItem.  This is a convience equivalent to
   69     getting the parent and its parent until there isn't a parent.
   70     */
   71     readonly attribute nsIDocShellTreeItem rootTreeItem;
   72 
   73     /*
   74     Returns the root DocShellTreeItem of the same type.  This is a convience
   75     equivalent to getting the parent of the same type and its parent until
   76     there isn't a parent.
   77     */
   78     readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem;
   79 
   80     /*
   81     Returns the docShellTreeItem with the specified name.  Search order is as
   82     follows...
   83     1.)  Check name of self, if it matches return it.
   84     2.)  For each immediate child.
   85         a.) Check name of child and if it matches return it.
   86         b.)  Ask the child to perform the check
   87             i.) Do not ask a child if it is the aRequestor
   88             ii.) Do not ask a child if it is of a different item type.
   89     3.)  If there is a parent of the same item type ask parent to perform the check
   90         a.) Do not ask parent if it is the aRequestor
   91     4.)  If there is a tab group ask the tab group to perform the check
   92         a.)  Do not ask the tab group if aSkipTabGroup
   93         b.)  This should only be done if there is no parent of the same type.
   94 
   95     Return the child DocShellTreeItem with the specified name.
   96     name - This is the name of the item that is trying to be found.
   97     aRequestor - This is the object that is requesting the find.  This
   98         parameter is used to identify when the child is asking its parent to find
   99         a child with the specific name.  The parent uses this parameter to ensure
  100         a resursive state does not occur by not again asking the requestor to find
  101         a shell by the specified name.  Inversely the child uses it to ensure it
  102         does not ask its parent to do the search if its parent is the one that
  103         asked it to search.  Children also use this to test against the treeOwner;
  104     aOriginalRequestor - The original treeitem that made the request, if any.
  105         This is used to ensure that we don't run into cross-site issues.
  106     aSkipTabGroup - Whether the tab group should be checked.
  107     */
  108     nsIDocShellTreeItem findItemWithName(in AString name,
  109                                          in nsIDocShellTreeItem aRequestor,
  110                                          in nsIDocShellTreeItem aOriginalRequestor,
  111                                          in bool aSkipTabGroup);
  112 
  113     /*
  114     The owner of the DocShell Tree.  This interface will be called upon when
  115     the docshell has things it needs to tell to the owner of the docshell.
  116     Note that docShell tree ownership does not cross tree types.  Meaning
  117     setting ownership on a chrome tree does not set ownership on the content
  118     sub-trees.  A given tree's boundaries are identified by the type changes.
  119     Trees of different types may be connected, but should not be traversed
  120     for things such as ownership.
  121 
  122     Note implementers of this interface should NOT effect the lifetime of the
  123     parent DocShell by holding this reference as it creates a cycle.  Owners
  124     when releasing this interface should set the treeOwner to nullptr.
  125     Implementers of this interface are guaranteed that when treeOwner is
  126     set that the poitner is valid without having to addref.
  127 
  128     Further note however when others try to get the interface it should be
  129     addref'd before handing it to them.
  130     */
  131     readonly attribute nsIDocShellTreeOwner treeOwner;
  132     [noscript] void setTreeOwner(in nsIDocShellTreeOwner treeOwner);
  133 
  134     /*
  135     The current number of DocShells which are immediate children of the
  136     this object.
  137     */
  138     readonly attribute long childCount;
  139 
  140     /*
  141     Add a new child DocShellTreeItem.  Adds to the end of the list.
  142     Note that this does NOT take a reference to the child.  The child stays
  143     alive only as long as it's referenced from outside the docshell tree.
  144     @throws NS_ERROR_ILLEGAL_VALUE if child corresponds to the same
  145             object as this treenode or an ancestor of this treenode
  146     @throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
  147     */
  148     void addChild(in nsIDocShellTreeItem child);
  149 
  150     /*
  151     Removes a child DocShellTreeItem.
  152     @throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
  153     */
  154     void removeChild(in nsIDocShellTreeItem child);
  155 
  156     /**
  157      * Return the child at the index requested.  This is 0-based.
  158      *
  159      * @throws NS_ERROR_UNEXPECTED if the index is out of range
  160      */
  161     nsIDocShellTreeItem getChildAt(in long index);
  162 
  163     /*
  164     Return the child DocShellTreeItem with the specified name.
  165     aName - This is the name of the item that is trying to be found.
  166     aRecurse - Is used to tell the function to recurse through children.
  167         Note, recursion will only happen through items of the same type.
  168     aSameType - If this is set only children of the same type will be returned.
  169     aRequestor - This is the docshellTreeItem that is requesting the find.  This
  170         parameter is used when recursion is being used to avoid searching the same
  171         tree again when a child has asked a parent to search for children.
  172     aOriginalRequestor - The original treeitem that made the request, if any.
  173         This is used to ensure that we don't run into cross-site issues.
  174 
  175     Note the search is depth first when recursing.
  176     */
  177     nsIDocShellTreeItem findChildWithName(in AString aName,
  178                                           in boolean aRecurse,
  179                                           in boolean aSameType,
  180                                           in nsIDocShellTreeItem aRequestor,
  181                                           in nsIDocShellTreeItem aOriginalRequestor);
  182 
  183   /**
  184    * Returns the DOM outer window for the content viewer.
  185    */
  186   readonly attribute mozIDOMWindowProxy domWindow;
  187 
  188   [noscript,nostdcall,notxpcom] Document getDocument();
  189   [noscript,nostdcall,notxpcom] nsPIDOMWindowOuter getWindow();
  190 };
  191