Gecko:Fullscreen API

From MozillaWiki
Jump to: navigation, search

(WIP)

This page is for documenting our Fullscreen API implementation.

Resources

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.

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

Most of this part is implemented in Bug 1161802.

Non-E10S

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) triggers nsGlobalWindow::FinishFullscreenChange() when the window enters fullscreen
  6. calls nsIDocument::HandlePendingFullscreenRequests()
  7. change the document state in nsDocument::ApplyFullscreen()

Exiting Fullscreen by Content

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

Exiting Fullscreen by User

(usually via escape key)

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

Exiting Fullscreen Unexpectedly

(page closure / navigation / fullscreen element removal)

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

E10S

Entering Fullscreen

  1. in the content process:
    1. the page calls Element.requestFullscreen() (Element::MozRequestFullScreen())
    2. (async) calls nsDocument::RequestFullscreen()
    3. dispatches MozDOMFullscreen:Request event to the chrome
    4. tab-content.js sends async message "DOMFullscreen:Request"
  2. in the parent process:
    1. browser-fullScreen.js calls nsDocument::RequestFullscreen()
    2. calls nsGlobalWindow::SetFullScreenInternal()
    3. calls widget to enter fullscreen
    4. (async) triggers nsGlobalWindow::FinishFullscreenChange() when the window enters fullscreen
    5. calls nsIDocument::HandlePendingFullscreenRequests()
    6. change the document state in nsDocument::ApplyFullscreen()
      • this step also dispatches MozDOMFullscreen:Entered to the chrome
    7. browser-fullScreen.js sends async message "DOMFullscreen:Entered"
  3. in the content process
    1. tab-content.js calls nsIDocument::HandlePendingFullscreenRequests()
    2. change the document state in nsDocument::ApplyFullscreen()

Exiting Fullscreen by Content

  1. in the content process:
    1. the page calls document.exitFullscreen() (nsDocument::MozCancelFullScreen())
    2. dispatches MozDOMFullscreen:Exit event to the chrome
    3. tab-content.js sends async message "DOMFullscreen:Exit"
  2. in the parent process:
    1. browser-fullScreen.js calls nsDocument::RestorePreviousFullScreenState()
    2. calls nsGlobalWindow::SetFullScreenInternal()
    3. calls widget to leave fullscreen
    4. (async) triggers nsGlobalWindow::FinishFullscreenChange() when the window exits fullscreen
    5. calls nsIDocument::ExitFullscreenInDocTree() which changes the document state
      • this step also dispatches MozDOMFullscreen:Exited to the chrome
    6. browser-fullScreen.js sends async message "DOMFullscreen:Exited"
  3. in the content process
    1. tab-content.js calls nsIDocument::ExitFullscreenInDocTree() which changes the document state

Exiting Fullscreen by User

Since user always uses the chrome to exit fullscreen

Exiting Fullscreen Unexpectedly

(navigation / fullscreen element removal)

  1. in the content process:
    1. two cases:
      • for navigation, nsDocument::OnPageHide()
      • for element removal, Element::UnbindFromTree()
    2. calls nsIDocument::ExitFullscreenInDocTree() which changes the document state
      • (may async) this step also dispatches MozDOMFullscreen:Exited to the chrome
    3. tab-content.js sends async message "DOMFullscreen:Exit"
  2. in the parent process:
    1. browser-fullScreen.js calls nsDocument::RestorePreviousFullScreenState()
    2. calls nsGlobalWindow::SetFullScreenInternal()
    3. calls widget to leave fullscreen
    4. (async) triggers nsGlobalWindow::FinishFullscreenChange() when the window exits fullscreen
    5. calls nsIDocument::ExitFullscreenInDocTree() which changes the document state

Browser Element

Transition

This part is implemented in Bug 1160014.