[whatwg] Proposal for a tab visibility API

[Bjartur Thorlacius]

On Wed, 08 Dec 2010 19:47:34 -0000, Alex Komoroske  
<komoroske at chromium.org> wrote:

> Hi all,
>
> 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.
>
> 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,

Minor semantic nitpick: please use the term /does not have focus/ rather  
than
/is a background tab/, as the latter is misleading in window managers that  
don't
use tabs to represent (all) windows. [Ninja'd]

> 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 (
> http://code.google.com/p/chromium/issues/detail?id=61745)  that Chromium  
> is
> currently in the early stages of experimentation with.
>
> ==Use cases==
> * 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.

Fair 'nuff (though I stress the importance of Web IDL APIs like this being  
specified separately from HTML).

> * A web app that uses polling to fetch dynamic content can pause polling
> when it knows the page is hidden from the user.

I argue that dynamic content should be declared as such. HTTP can hint at  
expiry of content, allowing UAs to automagically refetch content, but  
still allowing users to have the final say and set reasonable limits and  
take bandwidth constraints into consideration. I may not want to download  
that ad every two seconds over my metered mobile ad hoc network.

> * 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).

I don't see how autoplaying videos relate to Web IDL, but this is covered  
in other specifications. Autoplay is quite annoying, and there are other  
reasons for not automatically following links in pages and playing media  
recently downloaded, but I'm going OT.

> * A page wants to detect when it is being prerendered so it can behave
> appropriately.
> * A page wants to detect when it is moving into or out of the  
> back-forward
> cache.
>
Pass. Remember to take note of the existing SIGTSTP, in case there's  
anything to learn from history.

>
> With these use-cases in mind, there are a number of requirements.
>
> ==Requirements==
> * Easy for developers to write scripts that fall back on old behaviors  
> for
> browsers that do not implement this API
> * Ability to query the document’s current visibility state
> * Events fired when the document transitions between visibility states
> * Ability for browser vendors to add new visibility states in the future
>
Make a note of job/task managers potentially suspending unneded jobs, such  
as hidden/detached/backgrounded document (e.g. PDF, HTML) renderers.

>
> ==Strawman API==
> 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.
>
> =document.visibility=
> A read-only property that returns a string, one of:
> * “visible” : the tab is focused in its window
> * “hidden” : the tab is backgrounded within its window
Foremost, this makes more assumptions about the window management of the  
target system. Also, why would it be useful to know the focus of a tab  
inside of a window which may or may not be focused itself?

> =visibilitychanged=
> 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.
>
A property of visibilitychanged that hints at whether the program will  
continue executing or not.