From e0d1414c4a9e20d7676aa3f5bd46bb626652c38f Mon Sep 17 00:00:00 2001
From: Dave Johnson <davejohnson@dave-johnsons-macbook-pro.local>
Date: Mon, 26 Jul 2010 12:35:06 -0700
Subject: [PATCH] tweaks to PhoneGap.Channel

---
 example/phonegap.js                  | 24 +++----
 framework/assets/js/channel.js       | 81 ------------------------
 framework/assets/js/phonegap.js.base | 95 ++++++++++++++++++----------
 3 files changed, 72 insertions(+), 128 deletions(-)
 delete mode 100644 framework/assets/js/channel.js

diff --git a/example/phonegap.js b/example/phonegap.js
index 504eac87..9e8c8e27 100644
--- a/example/phonegap.js
+++ b/example/phonegap.js
@@ -142,19 +142,9 @@ PhoneGap.Channel.merge(function() {
 // Listen for DOMContentLoaded
 document.addEventListener('DOMContentLoaded', function() {
     PhoneGap.onDOMContentLoaded.fire();
-});
+}, false);
 
 
-// Intercept calls to document.addEventListener and watch for deviceready
-PhoneGap._document_addEventListener = document.addEventListener;
-
-document.addEventListener = function(evt, handler, capture) {
-    if (evt.toLowerCase() == 'deviceready') {
-        PhoneGap.onDeviceReady.sob(handler);
-    } else {
-        PhoneGap._document_addEventListener.call(document, evt, handler);
-    }
-};
 
 
 
@@ -638,7 +628,17 @@ Device.prototype.exitApp = function()
 
 PhoneGap.addConstructor(function() {
     navigator.device = window.device = new Device();
-});
+});// Intercept calls to document.addEventListener and watch for deviceready
+PhoneGap._document_addEventListener = document.addEventListener;
+
+document.addEventListener = function(evt, handler, capture) {
+    if (evt.toLowerCase() == 'deviceready') {
+        PhoneGap.onDeviceReady.sob(handler);
+    } else {
+        PhoneGap._document_addEventListener.call(document, evt, handler);
+    }
+};
+
 
 
 PhoneGap.addConstructor(function() { if (typeof navigator.fileMgr == "undefined") navigator.fileMgr = new FileMgr();});
diff --git a/framework/assets/js/channel.js b/framework/assets/js/channel.js
deleted file mode 100644
index 61757d71..00000000
--- a/framework/assets/js/channel.js
+++ /dev/null
@@ -1,81 +0,0 @@
-PhoneGap.Channel = function(type)
-{
-    this.type = type;
-    this.handlers = {};
-    this.guid = 0;
-    this.fired = false;
-    this.enabled = true;
-};
-
-PhoneGap.Channel.prototype.sub = function(f, c, g)
-{
-    // need a function to call
-    if (f == null)
-        return;
-
-    var func = f;
-    if (typeof c == "object" && f instanceof Function)
-        func = PhoneGap.close(c, f);
-
-    g = g || func.observer_guid || f.observer_guid || this.guid++;
-    func.observer_guid = g;
-    f.observer_guid = g;
-    this.handlers[g] = func;
-    return g;
-};
-
-PhoneGap.Channel.prototype.sob = function(f, c)
-{
-    var g = null;
-    var _this = this;
-    var m = function() {
-        f.apply(c || null, arguments);
-        _this.dub(g);
-    }
-    if (this.fired) {
-	    if (typeof c == "object" && f instanceof Function)
-	        f = PhoneGap.close(c, f);
-        f.apply(this, this.fireArgs);
-    } else {
-        g = this.sub(m);
-    }
-    return g;
-};
-
-PhoneGap.Channel.prototype.dub = function(g)
-{
-    if (g instanceof Function)
-        g = g.observer_guid;
-    this.handlers[g] = null;
-    delete this.handlers[g];
-};
-
-PhoneGap.Channel.prototype.fire = function(e)
-{
-    if (this.enabled)
-    {
-        var fail = false;
-        for (var item in this.handlers) {
-            var handler = this.handlers[item];
-            if (handler instanceof Function) {
-                var rv = (handler.apply(this, arguments)==false);
-                fail = fail || rv;
-            }
-        }
-        this.fired = true;
-        this.fireArgs = arguments;
-        return !fail;
-    }
-    return true;
-};
-
-PhoneGap.Channel.merge = function(h, e) {
-       var i = e.length;
-       var f = function() {
-           if (!(--i)) h();
-       }
-       for (var j=0; j<i; j++) {
-           (!e[j].fired?e[j].sob(f):i--);
-       }
-       if (!i) h();
-}
\ No newline at end of file
diff --git a/framework/assets/js/phonegap.js.base b/framework/assets/js/phonegap.js.base
index ede11040..15d17d7e 100755
--- a/framework/assets/js/phonegap.js.base
+++ b/framework/assets/js/phonegap.js.base
@@ -15,9 +15,9 @@ PhoneGap = {
 };
 
 
-
-
-
+/**
+ * Custom pub-sub channel that can have functions subscribed to it
+ */
 PhoneGap.Channel = function(type)
 {
     this.type = type;
@@ -27,15 +27,19 @@ PhoneGap.Channel = function(type)
     this.enabled = true;
 };
 
-PhoneGap.Channel.prototype.sub = function(f, c, g)
-{
+/**
+ * Subscribes the given function to the channel. Any time that 
+ * Channel.fire is called so too will the function.
+ * Optionally specify an execution context for the function
+ * and a guid that can be used to stop subscribing to the channel.
+ * Returns the guid.
+ */
+PhoneGap.Channel.prototype.subscribe = function(f, c, g) {
     // need a function to call
-    if (f == null)
-        return;
+    if (f == null) { return; }
 
     var func = f;
-    if (typeof c == "object" && f instanceof Function)
-        func = PhoneGap.close(c, f);
+    if (typeof c == "object" && f instanceof Function) { func = PhoneGap.close(c, f); }
 
     g = g || func.observer_guid || f.observer_guid || this.guid++;
     func.observer_guid = g;
@@ -44,36 +48,40 @@ PhoneGap.Channel.prototype.sub = function(f, c, g)
     return g;
 };
 
-PhoneGap.Channel.prototype.sob = function(f, c)
-{
+/**
+ * Like subscribe but the function is only called once and then it
+ * auto-unsubscribes itself.
+ */
+PhoneGap.Channel.prototype.subscribeOnce = function(f, c) {
     var g = null;
     var _this = this;
     var m = function() {
         f.apply(c || null, arguments);
-        _this.dub(g);
+        _this.unsubscribe(g);
     }
     if (this.fired) {
-	    if (typeof c == "object" && f instanceof Function)
-	        f = PhoneGap.close(c, f);
+	    if (typeof c == "object" && f instanceof Function) { f = PhoneGap.close(c, f); }
         f.apply(this, this.fireArgs);
     } else {
-        g = this.sub(m);
+        g = this.subscribe(m);
     }
     return g;
 };
 
-PhoneGap.Channel.prototype.dub = function(g)
-{
-    if (g instanceof Function)
-        g = g.observer_guid;
+/** 
+ * Unsubscribes the function with the given guid from the channel.
+ */
+PhoneGap.Channel.prototype.unsubscribe = function(g) {
+    if (g instanceof Function) { g = g.observer_guid; }
     this.handlers[g] = null;
     delete this.handlers[g];
 };
 
-PhoneGap.Channel.prototype.fire = function(e)
-{
-    if (this.enabled)
-    {
+/** 
+ * Calls all functions subscribed to this channel.
+ */
+PhoneGap.Channel.prototype.fire = function(e) {
+    if (this.enabled) {
         var fail = false;
         for (var item in this.handlers) {
             var handler = this.handlers[item];
@@ -89,20 +97,22 @@ PhoneGap.Channel.prototype.fire = function(e)
     return true;
 };
 
-PhoneGap.Channel.merge = function(h, e) {
-    var i = e.length;
+/**
+ * Calls the provided function only after all of the channels specified
+ * have been fired.
+ */
+PhoneGap.Channel.join = function(h, c) {
+    var i = c.length;
     var f = function() {
         if (!(--i)) h();
     }
     for (var j=0; j<i; j++) {
-        (!e[j].fired?e[j].sob(f):i--);
+        (!c[j].fired?c[j].subscribeOnce(f):i--);
     }
     if (!i) h();
 }
 
 
-
-
 /**
  * Boolean flag indicating if the PhoneGap API is available and initialized.
  */ // TODO: Remove this, it is unused here ... -jm
@@ -114,7 +124,7 @@ PhoneGap.available = DeviceInfo.uuid != undefined;
  * @param {Function} func The function callback you want run once PhoneGap is initialized
  */
 PhoneGap.addConstructor = function(func) {
-    PhoneGap.onDeviceReady.sob(function() {
+    PhoneGap.onDeviceReady.subscribeOnce(function() {
         try {
             func();
         } catch(e) {
@@ -127,22 +137,38 @@ PhoneGap.addConstructor = function(func) {
     });
 };
 
+/**
+ * onDOMContentLoaded channel is fired when the DOM content 
+ * of the page has been parsed.
+ */
 PhoneGap.onDOMContentLoaded = new PhoneGap.Channel();
+
+/**
+ * onNativeReady channel is fired when the PhoneGap native code
+ * has been initialized.
+ */
 PhoneGap.onNativeReady = new PhoneGap.Channel();
 
-if (_nativeReady) PhoneGap.onNativeReady.fire();
+// _nativeReady is global variable that the native side can set
+// to signify that the native code is ready. It is a global since 
+// it may be called before any PhoneGap JS is ready.
+if (_nativeReady) { PhoneGap.onNativeReady.fire(); }
 
+/**
+ * onDeviceReady is fired only after both onDOMContentLoaded and 
+ * onNativeReady have fired.
+ */
 PhoneGap.onDeviceReady = new PhoneGap.Channel();
 
-PhoneGap.Channel.merge(function() {
+PhoneGap.Channel.join(function() {
     PhoneGap.onDeviceReady.fire();
 }, [ PhoneGap.onDOMContentLoaded, PhoneGap.onNativeReady ]);
 
 
-// Listen for DOMContentLoaded
+// Listen for DOMContentLoaded and notify our channel subscribers
 document.addEventListener('DOMContentLoaded', function() {
     PhoneGap.onDOMContentLoaded.fire();
-});
+}, false);
 
 
 // Intercept calls to document.addEventListener and watch for deviceready
@@ -150,7 +176,7 @@ PhoneGap._document_addEventListener = document.addEventListener;
 
 document.addEventListener = function(evt, handler, capture) {
     if (evt.toLowerCase() == 'deviceready') {
-        PhoneGap.onDeviceReady.sob(handler);
+        PhoneGap.onDeviceReady.subscribeOnce(handler);
     } else {
         PhoneGap._document_addEventListener.call(document, evt, handler);
     }
@@ -158,7 +184,6 @@ document.addEventListener = function(evt, handler, capture) {
 
 
 
-
 /**
  * Execute a PhoneGap command in a queued fashion, to ensure commands do not
  * execute with any race conditions, and only run when PhoneGap is ready to