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.

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

class BrowsingContext

This is a synced-context type. Instances of it will exist in every “relevant” content process for the navigation.

Instances of BrowsingContext created in the parent processes will be CanonicalBrowsingContext.

WindowContext *GetParentWindowContext()

Get the parent WindowContext embedding this context, or nullptr, if this is the toplevel context.

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.

BrowsingContext *GetParent()
BrowsingContext *Top()
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.

class CanonicalBrowsingContext : public BrowsingContext

When a BrowsingContext is constructed in the parent process, it is actually an instance of CanonicalBrowsingContext.

Due to being in the parent process, more information about the context is available from a CanonicalBrowsingContext.

class WindowContext
class WindowGlobalParent : public WindowContext, public WindowGlobalActor, public PWindowGlobalParent
class WindowGlobalChild : public WindowGlobalActor, public PWindowGlobalChild