# BrowsingContext and WindowContext

The `BrowsingContext` is the Gecko representation of the spec-defined
[Browsing Context] object.

## 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.

```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>
```

```{eval-rst}
.. 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](https://wiki.mozilla.org/Project_Fission/BrowsingContext).

## API Documentation

```{eval-rst}
.. cpp:class:: BrowsingContext

  .. hlist::
    :columns: 3

    * :searchfox:`header (searchfox) <docshell/base/BrowsingContext.h>`
    * :searchfox:`source (searchfox) <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.
```

```{eval-rst}
.. cpp:class:: CanonicalBrowsingContext : public BrowsingContext

  .. hlist::
    :columns: 3

    * :searchfox:`header (searchfox) <docshell/base/CanonicalBrowsingContext.h>`
    * :searchfox:`source (searchfox) <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``.
```

```{eval-rst}
.. cpp:class:: WindowContext

  .. hlist::
    :columns: 3

    * :searchfox:`header (searchfox) <docshell/base/WindowContext.h>`
    * :searchfox:`source (searchfox) <docshell/base/WindowContext.cpp>`
```

```{eval-rst}
.. cpp:class:: WindowGlobalParent : public WindowContext, public WindowGlobalActor, public PWindowGlobalParent

  .. hlist::
    :columns: 3

    * :searchfox:`header (searchfox) <dom/ipc/WindowGlobalParent.h>`
    * :searchfox:`source (searchfox) <dom/ipc/WindowGlobalParent.cpp>`
```

```{eval-rst}
.. cpp:class:: WindowGlobalChild : public WindowGlobalActor, public PWindowGlobalChild

  .. hlist::
    :columns: 3

    * :searchfox:`header (searchfox) <dom/ipc/WindowGlobalChild.h>`
    * :searchfox:`source (searchfox) <dom/ipc/WindowGlobalChild.cpp>`
```

[browsing context]: https://html.spec.whatwg.org/multipage/browsers.html#browsing-context