Implement fullscreenchange/fullscreenerror event on document.

Author: kayahr

README.md

@@ -13,7 +13,7 @@ browsers (Like Chrome) and Firefox provide this new fullscreen feature.
 Usage
 -----
 
-### Entering Fullscreen mode ###
+### Entering Fullscreen mode
 
 You can either switch the whole page or a single HTML element to fullscreen
 mode:
@@ -25,7 +25,8 @@ This only works when the code was triggered by a user interaction (For
 example a onclick event on a button). Browsers don't allow entering
 fullscreen mode without user interaction.
 
-### Exiting Fullscreen mode ###
+
+### Exiting Fullscreen mode
 
 Fullscreen mode is always exited via the document but this plugin allows
 it also via any HTML element. The owner document of the selected HTML 
@@ -34,18 +35,37 @@ element is used then:
     $(document).fullScreen(false);
     $("#myVideo").fullScreen(false);
 
-### Querying Fullscreen mode ###
+
+### Querying Fullscreen mode
 
 Simply pass no argument to the `fullScreen` method to query the current
-state. The method returns `true` when fullscreen mode is active, `false`
-if not  or `null` when the browser does not support fullscreen mode at all.
+state.  The method returns the current fullscreen element (or true if
+browser doesn't support this) when fullscreen mode is active, `false` if not
+active or `null` when the browser does not support fullscreen mode at all. 
 So you can use this method also to display a fullscreen button only when the
 browser supports fullscreen mode:
 
     $("#fullscreenButton").toggle($(document).fullScreen() != null))
 
-### Toggling Fullscreen mode ###
+
+### Toggling Fullscreen mode
 
 The plugin provides another method for simple fullscreen mode toggling:
 
     $(document).toggleFullScreen();
+
+
+### Notifications
+
+The plugin triggers a `fullscreenchange` event on the document when the 
+fullscreen mode has been changed. If the browser rejected a fullscreen 
+state change then the plugin triggers a `fullscreenerror` event on the
+document. Example:
+
+    $(document).bind("fullscreenchange", function() {
+        console.log("Fullscreen " + $(document).fullScreen() ? "on" : "off);
+    });
+
+    $(document).bind("fullscreenerror", function() {
+        alert("Browser rejected fullscreen change");
+    });

jquery.fullscreen-min.js

@@ -1,5 +1,5 @@
 /** 
- * @preserve jquery.fullscreen 1.0.0
+ * @preserve jquery.fullscreen 1.1.0
  * https://github.com/kayahr/jquery-fullscreen-plugin
  * Copyright (C) 2012 Klaus Reimer <k@ailis.de>
  * Licensed under the MIT license
@@ -14,11 +14,14 @@
  * @param {boolean=} state
  *            True to enable fullscreen mode, false to disable it. If not
  *            specified then the current fullscreen state is returned.
- * @return {boolean|jQuery|null}
- *            When querying the fullscreen state then true, false or null
- *            is returned. Null indicates a browser without fullscreen
- *            support. When setting the state then the current jQuery
- *            selection is returned for chaining.
+ * @return {boolean|Element|jQuery|null}
+ *            When querying the fullscreen state then the current fullscreen
+ *            element (or true if browser doesn't support it) is returned
+ *            when browser is currently in full screen mode. False is returned
+ *            if browser is not in full screen mode. Null is returned if 
+ *            browser doesn't support fullscreen mode at all. When setting 
+ *            the fullscreen state then the current jQuery selection is 
+ *            returned for chaining.
  * @this {jQuery}
  */
 function fullScreen(state)
@@ -55,10 +58,18 @@ function fullScreen(state)
             return null;
         }
 
-        // Return the current fullscreen state
-        return !!doc["fullScreen"]
+        // Check fullscreen state
+        state = !!doc["fullScreen"]
             || !!doc["webkitIsFullScreen"]
             || !!doc["mozFullScreen"];
+        if (!state) return state;
+        
+        // Return current fullscreen element or "true" if browser doesn't
+        // support this
+        return (/** @type {?Element} */ doc["fullScreenElement"])
+            || (/** @type {?Element} */ doc["webkitCurrentFullScreenElement"])
+            || (/** @type {?Element} */ doc["mozFullScreenElement"])
+            || state;
     }
 
     // When state was specified then enter or exit fullscreen mode.
@@ -80,7 +91,7 @@ function fullScreen(state)
         if (func) func.call(doc);
         return this;
     }
-};
+}
 
 /**
  * Toggles the fullscreen mode.
@@ -93,9 +104,64 @@ function toggleFullScreen()
 {
     return (/** @type {!jQuery} */ fullScreen.call(this, 
         !fullScreen.call(this)));
-};
+}
+
+/**
+ * Handles the browser-specific fullscreenchange event and triggers
+ * a jquery event for it.
+ *
+ * @param {?Event} event
+ *            The fullscreenchange event.
+ */
+function fullScreenChangeHandler(event)
+{
+    jQuery(document).trigger(new jQuery.Event("fullscreenchange"));
+}
+
+/**
+ * Handles the browser-specific fullscreenerror event and triggers
+ * a jquery event for it.
+ *
+ * @param {?Event} event
+ *            The fullscreenerror event.
+ */
+function fullScreenErrorHandler(event)
+{
+    jQuery(document).trigger(new jQuery.Event("fullscreenerror"));
+}
+
+/**
+ * Installs the fullscreenchange event handler.
+ */
+function installFullScreenHandlers()
+{
+    var e, change, error;
+    
+    // Determine event name
+    e = document;
+    if (e["webkitCancelFullScreen"])
+    {
+        change = "webkitfullscreenchange";
+        error = "webkitfullscreenerror";
+    }
+    else if (e["mozCancelFullScreen"])
+    {
+        change = "mozfullscreenchange";
+        error = "mozfullscreenerror";
+    }
+    else 
+    {
+        change = "fullscreenchange";
+        error = "fullscreenerror";
+    }
+
+    // Install the event handlers
+    document.addEventListener(change, fullScreenChangeHandler, true);
+    document.addEventListener(error, fullScreenErrorHandler, true);
+}
 
 jQuery.fn["fullScreen"] = fullScreen;
 jQuery.fn["toggleFullScreen"] = toggleFullScreen;
+installFullScreenHandlers();
 
 })();