Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / Observable-more.html
index 2bd2141..faa7e7f 100644 (file)
@@ -1,41 +1,36 @@
-<html>
-<head>
-  <title>The source code</title>
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
-</head>
-<body  onload="prettyPrint();">
-    <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.0.3
- * Copyright(c) 2006-2009 Ext JS, LLC
- * licensing@extjs.com
- * http://www.extjs.com/license
- */
-/**\r
+<html>\r
+<head>\r
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
+  <title>The source code</title>\r
+    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
+    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
+</head>\r
+<body  onload="prettyPrint();">\r
+    <pre class="prettyprint lang-js">/**\r
  * @class Ext.util.Observable\r
  */\r
  * @class Ext.util.Observable\r
  */\r
-Ext.apply(Ext.util.Observable.prototype, function(){    \r
+Ext.apply(Ext.util.Observable.prototype, function(){\r
     // this is considered experimental (along with beforeMethod, afterMethod, removeMethodListener?)\r
     // allows for easier interceptor and sequences, including cancelling and overwriting the return value of the call\r
     // private\r
     function getMethodEvent(method){\r
         var e = (this.methodEvents = this.methodEvents ||\r
         {})[method], returnValue, v, cancel, obj = this;\r
     // this is considered experimental (along with beforeMethod, afterMethod, removeMethodListener?)\r
     // allows for easier interceptor and sequences, including cancelling and overwriting the return value of the call\r
     // private\r
     function getMethodEvent(method){\r
         var e = (this.methodEvents = this.methodEvents ||\r
         {})[method], returnValue, v, cancel, obj = this;\r
-        \r
+\r
         if (!e) {\r
             this.methodEvents[method] = e = {};\r
             e.originalFn = this[method];\r
             e.methodName = method;\r
             e.before = [];\r
             e.after = [];\r
         if (!e) {\r
             this.methodEvents[method] = e = {};\r
             e.originalFn = this[method];\r
             e.methodName = method;\r
             e.before = [];\r
             e.after = [];\r
-            \r
+\r
             var makeCall = function(fn, scope, args){\r
                 if (!Ext.isEmpty(v = fn.apply(scope || obj, args))) {\r
                     if (Ext.isObject(v)) {\r
                         returnValue = !Ext.isEmpty(v.returnValue) ? v.returnValue : v;\r
                         cancel = !!v.cancel;\r
                     }\r
             var makeCall = function(fn, scope, args){\r
                 if (!Ext.isEmpty(v = fn.apply(scope || obj, args))) {\r
                     if (Ext.isObject(v)) {\r
                         returnValue = !Ext.isEmpty(v.returnValue) ? v.returnValue : v;\r
                         cancel = !!v.cancel;\r
                     }\r
-                    else \r
+                    else\r
                         if (v === false) {\r
                             cancel = true;\r
                         }\r
                         if (v === false) {\r
                             cancel = true;\r
                         }\r
@@ -44,19 +39,19 @@ Ext.apply(Ext.util.Observable.prototype, function(){
                         }\r
                 }\r
             };\r
                         }\r
                 }\r
             };\r
-            \r
+\r
             this[method] = function(){\r
                 var args = Ext.toArray(arguments);\r
                 returnValue = v = undefined;\r
                 cancel = false;\r
             this[method] = function(){\r
                 var args = Ext.toArray(arguments);\r
                 returnValue = v = undefined;\r
                 cancel = false;\r
-                \r
+\r
                 Ext.each(e.before, function(b){\r
                     makeCall(b.fn, b.scope, args);\r
                     if (cancel) {\r
                         return returnValue;\r
                     }\r
                 });\r
                 Ext.each(e.before, function(b){\r
                     makeCall(b.fn, b.scope, args);\r
                     if (cancel) {\r
                         return returnValue;\r
                     }\r
                 });\r
-                \r
+\r
                 if (!Ext.isEmpty(v = e.originalFn.apply(obj, args))) {\r
                     returnValue = v;\r
                 }\r
                 if (!Ext.isEmpty(v = e.originalFn.apply(obj, args))) {\r
                     returnValue = v;\r
                 }\r
@@ -71,26 +66,26 @@ Ext.apply(Ext.util.Observable.prototype, function(){
         }\r
         return e;\r
     }\r
         }\r
         return e;\r
     }\r
-    \r
+\r
     return {\r
         // these are considered experimental\r
         // allows for easier interceptor and sequences, including cancelling and overwriting the return value of the call\r
     return {\r
         // these are considered experimental\r
         // allows for easier interceptor and sequences, including cancelling and overwriting the return value of the call\r
-        // adds an "interceptor" called before the original method\r
-        beforeMethod: function(method, fn, scope){\r
+        // adds an 'interceptor' called before the original method\r
+        beforeMethod : function(method, fn, scope){\r
             getMethodEvent.call(this, method).before.push({\r
                 fn: fn,\r
                 scope: scope\r
             });\r
         },\r
             getMethodEvent.call(this, method).before.push({\r
                 fn: fn,\r
                 scope: scope\r
             });\r
         },\r
-        \r
-        // adds a "sequence" called after the original method\r
-        afterMethod: function(method, fn, scope){\r
+\r
+        // adds a 'sequence' called after the original method\r
+        afterMethod : function(method, fn, scope){\r
             getMethodEvent.call(this, method).after.push({\r
                 fn: fn,\r
                 scope: scope\r
             });\r
         },\r
             getMethodEvent.call(this, method).after.push({\r
                 fn: fn,\r
                 scope: scope\r
             });\r
         },\r
-        \r
+\r
         removeMethodListener: function(method, fn, scope){\r
             var e = getMethodEvent.call(this, method), found = false;\r
             Ext.each(e.before, function(b, i, arr){\r
         removeMethodListener: function(method, fn, scope){\r
             var e = getMethodEvent.call(this, method), found = false;\r
             Ext.each(e.before, function(b, i, arr){\r
@@ -109,13 +104,13 @@ Ext.apply(Ext.util.Observable.prototype, function(){
                 });\r
             }\r
         },\r
                 });\r
             }\r
         },\r
-        \r
+\r
         <div id="method-Ext.util.Observable-relayEvents"></div>/**\r
          * Relays selected events from the specified Observable as if the events were fired by <tt><b>this</b></tt>.\r
          * @param {Object} o The Observable whose events this object is to relay.\r
          * @param {Array} events Array of event names to relay.\r
          */\r
         <div id="method-Ext.util.Observable-relayEvents"></div>/**\r
          * Relays selected events from the specified Observable as if the events were fired by <tt><b>this</b></tt>.\r
          * @param {Object} o The Observable whose events this object is to relay.\r
          * @param {Array} events Array of event names to relay.\r
          */\r
-        relayEvents: function(o, events){\r
+        relayEvents : function(o, events){\r
             var me = this;\r
             function createHandler(ename){\r
                 return function(){\r
             var me = this;\r
             function createHandler(ename){\r
                 return function(){\r
@@ -127,7 +122,7 @@ Ext.apply(Ext.util.Observable.prototype, function(){
                 o.on(ename, createHandler(ename), me);\r
             });\r
         },\r
                 o.on(ename, createHandler(ename), me);\r
             });\r
         },\r
-        \r
+\r
         <div id="method-Ext.util.Observable-enableBubble"></div>/**\r
          * <p>Enables events fired by this Observable to bubble up an owner hierarchy by calling\r
          * <code>this.getBubbleTarget()</code> if present. There is no implementation in the Observable base class.</p>\r
         <div id="method-Ext.util.Observable-enableBubble"></div>/**\r
          * <p>Enables events fired by this Observable to bubble up an owner hierarchy by calling\r
          * <code>this.getBubbleTarget()</code> if present. There is no implementation in the Observable base class.</p>\r
@@ -136,13 +131,13 @@ Ext.apply(Ext.util.Observable.prototype, function(){
          * access the required target more quickly.</p>\r
          * <p>Example:</p><pre><code>\r
 Ext.override(Ext.form.Field, {\r
          * access the required target more quickly.</p>\r
          * <p>Example:</p><pre><code>\r
 Ext.override(Ext.form.Field, {\r
-//  Add functionality to Field's initComponent to enable the change event to bubble\r
-    initComponent: Ext.form.Field.prototype.initComponent.createSequence(function() {\r
+    //  Add functionality to Field&#39;s initComponent to enable the change event to bubble\r
+    initComponent : Ext.form.Field.prototype.initComponent.createSequence(function() {\r
         this.enableBubble('change');\r
     }),\r
 \r
         this.enableBubble('change');\r
     }),\r
 \r
-//  We know that we want Field's events to bubble directly to the FormPanel.\r
-    getBubbleTarget: function() {\r
+    //  We know that we want Field&#39;s events to bubble directly to the FormPanel.\r
+    getBubbleTarget : function() {\r
         if (!this.formPanel) {\r
             this.formPanel = this.findParentByType('form');\r
         }\r
         if (!this.formPanel) {\r
             this.formPanel = this.findParentByType('form');\r
         }\r
@@ -157,15 +152,15 @@ var myForm = new Ext.formPanel({
     }],\r
     listeners: {\r
         change: function() {\r
     }],\r
     listeners: {\r
         change: function() {\r
-//          Title goes red if form has been modified.\r
-            myForm.header.setStyle("color", "red");\r
+            // Title goes red if form has been modified.\r
+            myForm.header.setStyle('color', 'red');\r
         }\r
     }\r
 });\r
 </code></pre>\r
         }\r
     }\r
 });\r
 </code></pre>\r
-         * @param {Object} events The event name to bubble, or an Array of event names.\r
+         * @param {String/Array} events The event name to bubble, or an Array of event names.\r
          */\r
          */\r
-        enableBubble: function(events){\r
+        enableBubble : function(events){\r
             var me = this;\r
             if(!Ext.isEmpty(events)){\r
                 events = Ext.isArray(events) ? events : Ext.toArray(arguments);\r
             var me = this;\r
             if(!Ext.isEmpty(events)){\r
                 events = Ext.isArray(events) ? events : Ext.toArray(arguments);\r
@@ -189,9 +184,9 @@ var myForm = new Ext.formPanel({
  * to the supplied function with the event name + standard signature of the event\r
  * <b>before</b> the event is fired. If the supplied function returns false,\r
  * the event will not fire.\r
  * to the supplied function with the event name + standard signature of the event\r
  * <b>before</b> the event is fired. If the supplied function returns false,\r
  * the event will not fire.\r
- * @param {Observable} o The Observable to capture\r
- * @param {Function} fn The function to call\r
- * @param {Object} scope (optional) The scope (this object) for the fn\r
+ * @param {Observable} o The Observable to capture events from.\r
+ * @param {Function} fn The function to call when an event is fired.\r
+ * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the function is executed. Defaults to the Observable firing the event.\r
  * @static\r
  */\r
 Ext.util.Observable.capture = function(o, fn, scope){\r
  * @static\r
  */\r
 Ext.util.Observable.capture = function(o, fn, scope){\r
@@ -206,17 +201,23 @@ Ext.util.Observable.capture = function(o, fn, scope){
  * <p>Usage:</p><pre><code>\r
 Ext.util.Observable.observeClass(Ext.data.Connection);\r
 Ext.data.Connection.on('beforerequest', function(con, options) {\r
  * <p>Usage:</p><pre><code>\r
 Ext.util.Observable.observeClass(Ext.data.Connection);\r
 Ext.data.Connection.on('beforerequest', function(con, options) {\r
-    console.log("Ajax request made to " + options.url);\r
+    console.log('Ajax request made to ' + options.url);\r
 });</code></pre>\r
  * @param {Function} c The class constructor to make observable.\r
 });</code></pre>\r
  * @param {Function} c The class constructor to make observable.\r
+ * @param {Object} listeners An object containing a series of listeners to add. See {@link #addListener}. \r
  * @static\r
  */\r
  * @static\r
  */\r
-Ext.util.Observable.observeClass = function(c){\r
-    Ext.apply(c, new Ext.util.Observable());\r
-    c.prototype.fireEvent = function(){\r
-        return (c.fireEvent.apply(c, arguments) !== false) &&\r
-        (Ext.util.Observable.prototype.fireEvent.apply(this, arguments) !== false);\r
-    };\r
-};</pre>
-</body>
+Ext.util.Observable.observeClass = function(c, listeners){\r
+    if(c){\r
+      if(!c.fireEvent){\r
+          Ext.apply(c, new Ext.util.Observable());\r
+          Ext.util.Observable.capture(c.prototype, c.fireEvent, c);\r
+      }\r
+      if(Ext.isObject(listeners)){\r
+          c.on(listeners);\r
+      }\r
+      return c;\r
+   }\r
+};</pre>    \r
+</body>\r
 </html>
\ No newline at end of file
 </html>
\ No newline at end of file