Re: [Page Visibility] Spec Updates

Hi Jatinder,

Thanks for working on this draft!  I have a few comments inline (if I don't
have a comment on something, it's because I think it's a great change).

On Wed, May 4, 2011 at 11:21 AM, Jatinder Mann <jmann@microsoft.com> wrote:

>  I have updated the Page Visibility specification draft:
> http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html
> .
>
>
>
> I have made the following changes:
>
>
>
> *1.      **Window rather than Navigator implements WindowVisibility
> interface *
>
> Per feedback, I have updated the spec to have Window rather than Navigator
> implement the WindowVisibility interface.
>
>
> In the original thread on the subject I proposed exposing these properties
on Document (rather than Window or Navigator).  That has the nice property
of extremely decreased odds of collision with global variables in existing
scripts.

>
> *3.      **Visibility definitions generalized*
>
> I have generalized the definitions of visibility from my previous very
> specific cases. I have defined page visibility as the visibility state of
> the Document contained by the top level browsing context (root window in the
> browser's viewport). For example, window.visible is true when the Document
> contained by the top level browsing context (root window in the browser's
> viewport) is at least partially visible on at least one screen. I have left
> examples of the specific cases.
>
> * *
>
In later discussion in the public-webapps thread, we decided to change the
meaning of "visible" to " the page content *may* be at least partially
visible", because the spec does not require that user agents report hidden
when a non-minimized window happens to be fully obscured by another window.



A couple of other things I wanted to comment on in the draft:

*Numerical constants for visibilityState*
The draft proposes that visibilityState returns numerical constants, but in
the original proposal visibilityState returned strings.  I prefer the string
approach for the following reasons:

   - A string-based API is more webby and easier to use
   - A string-based API is easier to expand in the future with more return
   values, including vendor-prefixed ones.  For example, WebKit could start
   exposing "webkit-partially-hidden" in advance of "partially-hidden" being a
   formal part of the spec.
   - A string-based API is easier to use for feature-detection in scripts,
   because document.visibilityState would only return false-y values (i.e.
   undefined) in browsers that don't support the API.  As currently specified,
   the PAGE_HIDDEN constant is false-y, which makes it ever so slightly more
   difficult to feature-detect.

*Semantics of PAGE_PREVIEW*
In the original thread the discussion settled on "the page may be at least
partially visible, but not in an interactive form" for the semantics of
"preview", where the relevant part is that it's non-interactive.  I like the
"non-interactive" component being part of the semantics, because I think it
captures nicely what a preview means.
*
*
*User Agents MUST return PAGE_PREVIEW, etc*
In the original draft, conforming user agents MUST return "hidden" and
"visible" for visibilityState, and MAY* *return the other values
("prerender", "preview", "cache", future values) if they choose to.  The
reason was that:

   - A less stringent requirement allows user agents to implement the easier
   core of the API first, and follow later (if they choose) with the
   supplemental values
   - It could conceivably be expensive to fire a javascript event each time
   a preview of a page will be shown (which should be a fast operation), so we
   wanted to leave it up to the user agent to make the call based on
   performance considerations

For reference, I've included the text of the original informal draft after
including all of the changes the public-webapps thread proposed.

Thanks,
Alex Komoroske


-------

==Text of informal proposal as discussed on public-webapps==

=document.visible=
Returns true if document.visibilityState’s current value is in the set of
visibility states considered to be visible (see the next section for
information on document.visibilityState).  In practice document.visible is
merely a convenience property that is well-suited to simple uses.

The “visible” state is considered to be visible in all implementations.
 “hidden”, “prerender”, and “cache” are considered to be hidden in all
implementations.  The visibility of additional values, including “preview”,
are up to the discretion of the implementation (for example, an
implementation that makes use of nearly-full-size thumbnail previews may
consider “preview” to be a visible state).

=document.visibilityState=
A read-only property that returns a string, one of the values described in
the next section.  Developers can use the existence of this property to know
that they can rely on the rest of this API, too.
Values returned by all conforming implementations
   * “visible” : the page content may be at least partially visible.
   * “hidden” : the page content is not visible to the user at all.
Additional values potentially returned by some implementations in some cases
   * “prerender” : the page is currently being loaded off-screen and might
never be shown to the user.
   * “cache” : the page is currently “frozen” in a cache and not displayed
on screen (e.g. the back-forward cache).
   * “preview” : the page may be at least partially visible, but not in an
interactive form (e.g. a lower-resolution thumbnail when switching between
tabs).


Page refers to the top-most containing page for the document (i.e. embedded
frames get the visibility state of the window at the top of the window
hierarchy).

States in the second set are not guaranteed to be returned in all cases
where they might otherwise appear to apply--it is left to the discretion of
the implementation.

Additional return values may be added to this API in the future.

It is up to the implementation to interpret what these values mean in the
precise context of interface and platform.  As an example, a
current-generation desktop browser might interpret the values the following
way:
“visible” : the tab is focused in its non-minimized window (regardless of
the focus state of the containing window).
“hidden” : the tab is backgrounded within its window, or the containing
window is minimized.


=visibilitychange=
A simple event, fired at the document object immediately after
document.visibilityState transitions between visibility states.  The event
has two properties, fromState and wasVisible, that are set to the value of
document.visibilityState and document.visible, respectively,  just before
they were 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.