Thursday 10 November 2011

Firefox's HTML full-screen API enabled in Nightly builds

A few days ago I enabled the HTML full-screen API in Firefox nightly builds. This enables developers to make an arbitrary HTML element "full-screen", hiding the browser's UI and stretching the element to encompass the entire screen. This will be particularly useful for HTML5 video and games.

If all goes well, this feature will ship in Firefox 10 at the end of January.

The API has changed slightly since I last blogged about it. The current API is Mozilla-specific, but is similar to the W3C's Fullscreen draft specification.

To enter full-screen mode, call the following method on the HTML Element you'd like to enter full-screen:
  • void mozRequestFullScreen() : posts an asynchronous request to make the HTML element the full-screen element. If the request is granted, some time later a bubbling "mozfullscreenchange" event is dispatched to the element which requested full-screen. If the request is denied, a "mozfullscreenerror" event is dispatched to the element's owning document. We only grant requests for full-screen when:
    • mozRequestFullScreen() is called in a user-generated event handler, e.g. a mouse click handler, and
    • the requesting element is in its document, and
    • there are no windowed plugins present in any document/iframe in the current page, and
    • all iframes containing the requesting element (if any) have the mozallowfullscreen attribute.
We added the following method and attributes to HTML Document:
  • void mozCancelFullScreen() : exits the document from full-screen mode. This dispatches a "mozfullscreenchange" event to the document containing the (now former) full-screen element. Note that the "mozfullscreenchange" event which is dispatched when you enter full-screen is targeted at the full-screen element, so if you want to receive the "mozfullscreenchange" on both entering and exiting full-screen in the same listener you should add your listener to the document, rather than the full-screen element.
  • readonly attribute boolean mozFullScreen : true when the document is in full-screen mode.
  • readonly attribute Element mozFullScreenElement : reference to the current full-screen element.
  • readonly attribute boolean mozFullScreenEnabled : returns true if calls to mozRequestFullScreen() would be granted in the current document. This returns false if there are any windowed plugins present in any document/iframe in the current page, or if any iframes containing this document don't have the mozallowfullscreen attribute present, or if the user has disabled the API by preference. If this returns false you may want to not show the user your enter-full-screen button in your page, since you know it won't work!
We also added the :-moz-full-screen css pseudo class, which applies to the full-screen element while in full-screen mode.

We added the mozallowfullscreen attribute to iframe elements. Without this, full-screen requests made by script in the iframe's content (i.e embedded ads, or a YouTube player in an iframe for that matter) will be denied.

While in full-screen mode, the user can press the ESC key (or F11) to exit. Alpha-numeric keyboard input while in full-screen mode causes a warning message to pop-up to guard against phishing attacks. The only key input which doesn't cause the warning message to pop up are: left, right, up, down, space, shift, control, alt, page up, page down, end, home, tab, and meta.

Navigating, changing tab, changing app (ALT+TAB) while in full-screen mode will cause full-screen mode to exit.

Here's about a simple example, which will work in current Firefox nightly builds:




(Press ESC to exit full-screen)

The code for that button's onclick handler is simply:
document.getElementById('bruce_video').mozRequestFullScreen();

How is Firefox's full-screen API different from Webkit/Chrome/Safari's full-screen API? Firefox's API adds a "width: 100%; height: 100%;" CSS rule to the element which requests full-screen, so that it's stretched to occupy the entire screen. Chrome's API does not do this, but instead it centers the full-screen element in the window and blacks-out the underlying webpage. So the full-screen element won't occupy the entire screen with Chrome's API unless you specify a "width: 100%; height: 100%;" rule yourself. Conversely if you want to vertically and horizontally center something while in full-screen with Firefox's API, you need to make the containing element of your desired centered element full-screen instead, and apply CSS rules to vertically and horizontally center the contained element.

For a cross-browser full-screen API example, see html5-demos.appspot.com's full-screen demo.

Edit: 11 Nov 2011, clarified Document.mozCancelFullScreen() and Document.mozFullScreenEnabled, fixed typos.

14 comments:

Lozzy said...

Excellent, great to be able to test this out and see the progress. It's also great to see that alphanumeric restrictions are being relaxed, though I tend to feel it needs to be relaxed a little more; having that message pop up every time I move my FPS character would be quite distracting. Just show the warning the first time alphanumeric entry is made?

Also, I noticed that when fulscreening a video element, the video controld are persistent, which doesn't seem desirable. And the mouse continues to be visible.

I know there's a good chance I'm jumping the gun with these points, but I thought the feedback would be worthwhile regardless.

Anonymous said...

Nice!

FYI your [Make video full-screen] button fails with no console errors if run from planet.mozilla.org. Lots of demos fail when run from Planet Mozilla, I'm not sure how posts can check this, maybe a generic `if (window.location == not my blog)`. Also, it would be better sample code to check for document.getElementById("bruce_video").mozRequestFullScreen and warn "Requires a newer Mozilla browser?" instead of the button.

Anonymous said...

What prevents sites from abusing this? Various sites still attempt to pop up ads and such the first time the user clicks anywhere on the page; now they have the ability to full-screen the page for added annoyance. What about a mechanism to explicitly request user permission, and whitelist sites which may use fullscreen?

Chris Pearce said...

@Laurence: Yeah, there's a bug on file to make the video controls when in full-screen.

@skierpage: Yes, unfortunately planet.mozilla.org strips out the button onclick handler so the example doesn't work on p.m.o. :(

@Anon1aPEmU8A: The API has been implemented asynchronously so that permission dialogs can be added if needed. In the case you describe the user can press ESC to exit it easily, slightly more convenient than other types of popup abuse.

Anonymous said...

I've downloaded and started Nightly but clicking on the button in your post just does nothing. No fullscreen, no message in console.

What am I doing wrong?

Chris Pearce said...

@Max: Are you trying the demo on planet.mozilla.org or planet.xiph.org? p.m.o. strips onclick handlers from syndicated posts, so the demo isn't working on p.m.o. and p.x.o may be doing the same.

Also check that you have the pref "full-screen-api.enabled" set to "true".

Anonymous said...

@Chris: I'm trying it directly on your website (blog.pearce.org.nz) using the nightly build from 2011-11-16.

full-screen-api.enabled is true.

I run Nightly in a VirtualBox VM, though. Could that impede the functionality of the API?

Max

Anonymous said...

@Chris: A'right, I started directly on the host (without VirtualBox) and it works. So it definitely has sth. to do with Nightly running in a guest env of VirtualBox.

Castles said...

Is there any plans for Fullscreen Dual Monitor Support? This would be great for a Power Point Style Website I'm planning on building.

Currently if I create a popup and make it fullscreen on 2nd monitor it works but as soon as I go to my primary monitor to control it the fullscreen exits.

Chris Pearce said...

@Castles: Currently no plans to do that. We're worried that a full-screen page on another monitor could pretend to be the users desktop if that was allowed.

Anonymous said...

A huge nagging message make it useless for any interactive content. I've tried it for distraction free editing. Another example may be games.

At the End of the Day said...

This is interesting. I am searching for a replacement for IE's kiosk mode switch in XBMC.

I would like to switch out the external browser with Chrome or Firefox.

Is there anyway we can have a command line switch in a nightly build to test?

Skipser said...

Here's a trick to make Firefox open in full screen when ever you open it.

Unknown said...

thanks team