<div>Hi all,</div><div><br></div><div>On the Chromium team we’ve identified a couple of use cases that we’d like to address with a simple API, and we’d love your feedback.</div><div><br></div><div>In particular, there is currently no good way for a web page to detect that it is a background tab and is thus completely invisible to the user, although some heuristics do exist (like detecting mousemove events).  In the future, there may be cases where such detection is even more important, for example in the prerendering feature (<a href="http://code.google.com/p/chromium/issues/detail?id=61745" target="_blank">http://code.google.com/p/chromium/issues/detail?id=61745</a>)  that Chromium is currently in the early stages of experimentation with.</div>


<div><br></div><div>==Use cases==</div><div>* A puzzle game has a timer that keeps track of how long the user has taken to solve the puzzle.  It wants to pause the timer when the user has hidden the tab.</div><div>* A web app that uses polling to fetch dynamic content can pause polling when it knows the page is hidden from the user.</div>


<div>* A streaming video site doesn’t want to start the video until the user actually views the tab for the first time (i.e. video shouldn’t start automatically if a user opens the tab in the background).</div><div>* A page wants to detect when it is being prerendered so it can behave appropriately.</div>


<div>* A page wants to detect when it is moving into or out of the back-forward cache.</div><div><br></div><div><br></div><div>With these use-cases in mind, there are a number of requirements.</div><div><br></div><div>==Requirements==</div>


<div>* Easy for developers to write scripts that fall back on old behaviors for browsers that do not implement this API</div><div>* Ability to query the document’s current visibility state</div><div>* Events fired when the document transitions between visibility states</div>


<div>* Ability for browser vendors to add new visibility states in the future</div><div><br></div><div><br></div><div>==Strawman API==</div><div>What follows is a proposed API that fits the requirements.  Note that another route would be to attempt a mostly-compatible extension of Mozilla’s existing pageshow and pagehide events, which would not necessarily be perfectly backwards compatible.</div>


<div><br></div><div>=document.visibility=</div><div>A read-only property that returns a string, one of:</div><div>* “visible” : the tab is focused in its window</div><div>* “hidden” : the tab is backgrounded within its window</div>


<div>* “prerender” : the tab is currently being loaded in an off-screen tab, and may never be shown to the user.</div><div>* “cache” : the tab is currently in the back-forward-cache.  Note that in Mozilla’s current implementation, document.visibility would never actually be “cache” because Javascript cannot execute when in the cache.</div>

<div><br></div>
<div>In the future, the list of possible values may be extended.  Of these states in this list, all except “visible” are considered to be hidden.  Developers can use the existence of this property to know that they can rely on the rest of this API, too.</div>


<div><br></div><div>=document.isVisible=</div><div>A simple convenience read-only property that returns a boolean. Returns true if document.visibility’s current value is in the set of visibility states considered to be visible (for the first iteration of this API, that would only include the “visible” state).</div>


<div><br></div><div>=visibilitychanged=</div><div>A simple event, fired at the document object immediately after document.visibility transitions between visibility states.  The event has a property, fromState, that is set to the value of document.visibility just before it was changed to the current value.  Note that visibility has nothing to do with whether the document’s contents have fully loaded or not, which implies that for any given visibility transition event, onload may or may not have already fired.</div>


<div><br></div><div>Thoughts or comments are welcome.</div><div><br></div><div>--Alex Komoroske</div>