BrowsingContext.rst (4886B)
1 BrowsingContext and WindowContext 2 ================================= 3 4 The ``BrowsingContext`` is the Gecko representation of the spec-defined 5 `Browsing Context`_ object. 6 7 .. _Browsing Context: https://html.spec.whatwg.org/multipage/browsers.html#browsing-context 8 9 10 The Browsing Context Tree 11 ------------------------- 12 13 ``BrowsingContext`` and ``WindowContext`` objects form a tree, corresponding 14 to the tree of frame elements which was used to construct them. 15 16 17 Example 18 ^^^^^^^ 19 20 Loading the HTML documents listed here, would end up creating a set of BrowsingContexts and WindowContexts forming the tree. 21 22 .. code-block:: html 23 24 <!-- http://example.com/top.html --> 25 <iframe src="frame1.html"></iframe> 26 <iframe src="http://mozilla.org/"></iframe> 27 28 <!-- http://example.com/frame1.html --> 29 <iframe src="http://example.com/frame2.html"></iframe> 30 31 <!-- http://mozilla.org --> 32 <iframe></iframe> 33 <iframe></iframe> 34 35 .. digraph:: browsingcontext 36 37 node [shape=rectangle] 38 39 "BC1" [label="BrowsingContext A"] 40 "BC2" [label="BrowsingContext B"] 41 "BC3" [label="BrowsingContext C"] 42 "BC4" [label="BrowsingContext D"] 43 "BC5" [label="BrowsingContext E"] 44 "BC6" [label="BrowsingContext F"] 45 46 "WC1" [label="WindowContext\n(http://example.com/top.html)"] 47 "WC2" [label="WindowContext\n(http://example.com/frame1.html)"] 48 "WC3" [label="WindowContext\n(http://mozilla.org)"] 49 "WC4" [label="WindowContext\n(http://example.com/frame2.html)"] 50 "WC5" [label="WindowContext\n(about:blank)"] 51 "WC6" [label="WindowContext\n(about:blank)"] 52 53 "BC1" -> "WC1"; 54 "WC1" -> "BC2"; 55 "WC1" -> "BC3"; 56 "BC2" -> "WC2"; 57 "BC3" -> "WC3"; 58 "WC2" -> "BC4"; 59 "BC4" -> "WC4"; 60 "WC3" -> "BC5"; 61 "BC5" -> "WC5"; 62 "WC3" -> "BC6"; 63 "BC6" -> "WC6"; 64 65 66 Synced Fields 67 ------------- 68 69 WIP - In-progress documentation at `<https://wiki.mozilla.org/Project_Fission/BrowsingContext>`_. 70 71 72 API Documentation 73 ----------------- 74 75 .. cpp:class:: BrowsingContext 76 77 .. hlist:: 78 :columns: 3 79 80 * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/BrowsingContext.h>`_ 81 * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/BrowsingContext.cpp>`_ 82 * `html spec <https://html.spec.whatwg.org/multipage/browsers.html#browsing-context>`_ 83 84 This is a synced-context type. Instances of it will exist in every 85 "relevant" content process for the navigation. 86 87 Instances of :cpp:class:`BrowsingContext` created in the parent processes 88 will be :cpp:class:`CanonicalBrowsingContext`. 89 90 .. cpp:function:: WindowContext* GetParentWindowContext() 91 92 Get the parent ``WindowContext`` embedding this context, or ``nullptr``, 93 if this is the toplevel context. 94 95 .. cpp:function:: WindowContext* GetTopWindowContext() 96 97 Get the toplevel ``WindowContext`` embedding this context, or ``nullptr`` 98 if this is the toplevel context. 99 100 This is equivalent to repeatedly calling ``GetParentWindowContext()`` 101 until it returns nullptr. 102 103 .. cpp:function:: BrowsingContext* GetParent() 104 105 .. cpp:function:: BrowsingContext* Top() 106 107 .. cpp:function:: static already_AddRefed<BrowsingContext> Get(uint64_t aId) 108 109 Look up a specific ``BrowsingContext`` by it's unique ID. Callers should 110 check if the returned context has already been discarded using 111 ``IsDiscarded`` before using it. 112 113 .. cpp:class:: CanonicalBrowsingContext : public BrowsingContext 114 115 .. hlist:: 116 :columns: 3 117 118 * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/CanonicalBrowsingContext.h>`_ 119 * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/CanonicalBrowsingContext.cpp>`_ 120 121 When a :cpp:class:`BrowsingContext` is constructed in the parent process, 122 it is actually an instance of :cpp:class:`CanonicalBrowsingContext`. 123 124 Due to being in the parent process, more information about the context is 125 available from a ``CanonicalBrowsingContext``. 126 127 .. cpp:class:: WindowContext 128 129 .. hlist:: 130 :columns: 3 131 132 * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/WindowContext.h>`_ 133 * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/WindowContext.cpp>`_ 134 135 .. cpp:class:: WindowGlobalParent : public WindowContext, public WindowGlobalActor, public PWindowGlobalParent 136 137 .. hlist:: 138 :columns: 3 139 140 * `header (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalParent.h>`_ 141 * `source (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalParent.cpp>`_ 142 143 .. cpp:class:: WindowGlobalChild : public WindowGlobalActor, public PWindowGlobalChild 144 145 .. hlist:: 146 :columns: 3 147 148 * `header (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalChild.h>`_ 149 * `source (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalChild.cpp>`_