Gecko:Fullscreen API

(WIP)

This page is for documenting our Fullscreen API implementation.

Resources

• Fullscreen API spec
• Fullscreen design from :Verdi also includes some background info

Basic Control Flow

The flow of how Fullscreen API works is a bit complicated because we want to change the state of the document after the window enters or leaves fullscreen, so that we can:

1. provide a stable viewport size when we notify the content, and
2. insert fullscreen transition there.

This flow is different for non-e10s, e10s, and the browser element, because we need to go across the process boundary in later cases.

Non-E10S

For entering fullscreen:

1. the page calls Element.requestFullscreen() (Element::MozRequestFullScreen())
2. (async) calls nsDocument::RequestFullscreen()
3. calls nsGlobalWindow::SetFullScreenInternal()
4. calls widget to enter fullscreen
5. (async) calls nsGlobalWindow::FinishFullscreenChange() <-- triggers when the window enters fullscreen
6. calls nsIDocument::HandlePendingFullscreenRequests()
7. change the document state in nsDocument::ApplyFullscreen()

For exiting fullscreen by page:

1. the page calls document.exitFullscreen() (nsDocument::MozCancelFullScreen())
2. calls nsGlobalWindow::SetFullScreenInternal()
3. calls widget to leave fullscreen
4. (async) calls nsGlobalWindow::FinishFullscreenChange() <-- triggers when the window exits fullscreen
5. calls nsIDocument::ExitFullscreenInDocTree() which changes the document state

For exiting fullscreen by user (via escape key):

1. in PresShell::HandleEventInternal()
2. calls nsIDocument::AsyncExitFullscreen()
3. (async) calls nsGlobalWindow::SetFullscreenInternal()
4. then same as above...

For exiting fullscreen unexpectedly (page closure / fullscreen element removal):

1. in nsDocument::OnPageHide() (for page closure) / Element::UnbindFromTree() (for element removal)
2. calls nsIDocument::ExitFullscreenInDocTree() which changes the document state
3. (may async) calls nsGlobalWindow::SetFullscreenInternal()
4. calls widget to leave fullscreen