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