Upgrade to ExtJS 3.2.1 - Released 04/27/2010
[extjs.git] / docs / source / Observable-more.html
index faa7e7f..42132bf 100644 (file)
-<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
-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
-\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
-            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
-                        if (v === false) {\r
-                            cancel = true;\r
-                        }\r
-                        else {\r
-                            returnValue = v;\r
-                        }\r
-                }\r
-            };\r
-\r
-            this[method] = function(){\r
-                var args = Ext.toArray(arguments);\r
-                returnValue = v = undefined;\r
-                cancel = false;\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
-                if (!Ext.isEmpty(v = e.originalFn.apply(obj, args))) {\r
-                    returnValue = v;\r
-                }\r
-                Ext.each(e.after, function(a){\r
-                    makeCall(a.fn, a.scope, args);\r
-                    if (cancel) {\r
-                        return returnValue;\r
-                    }\r
-                });\r
-                return returnValue;\r
-            };\r
-        }\r
-        return e;\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
-        // 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
-\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
-\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
-                if (b.fn == fn && b.scope == scope) {\r
-                    arr.splice(i, 1);\r
-                    found = true;\r
-                    return false;\r
-                }\r
-            });\r
-            if (!found) {\r
-                Ext.each(e.after, function(a, i, arr){\r
-                    if (a.fn == fn && a.scope == scope) {\r
-                        arr.splice(i, 1);\r
-                        return false;\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
-        relayEvents : function(o, events){\r
-            var me = this;\r
-            function createHandler(ename){\r
-                return function(){\r
-                    return me.fireEvent.apply(me, [ename].concat(Ext.toArray(arguments)));\r
-                };\r
-            }\r
-            Ext.each(events, function(ename){\r
-                me.events[ename] = me.events[ename] || true;\r
-                o.on(ename, createHandler(ename), me);\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
-         * <p>This is commonly used by Ext.Components to bubble events to owner Containers. See {@link Ext.Component.getBubbleTarget}. The default\r
-         * implementation in Ext.Component returns the Component's immediate owner. But if a known target is required, this can be overridden to\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&#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
-    //  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
-        return this.formPanel;\r
-    }\r
-});\r
-\r
-var myForm = new Ext.formPanel({\r
-    title: 'User Details',\r
-    items: [{\r
-        ...\r
-    }],\r
-    listeners: {\r
-        change: function() {\r
-            // Title goes red if form has been modified.\r
-            myForm.header.setStyle('color', 'red');\r
-        }\r
-    }\r
-});\r
-</code></pre>\r
-         * @param {String/Array} events The event name to bubble, or an Array of event names.\r
-         */\r
-        enableBubble : function(events){\r
-            var me = this;\r
-            if(!Ext.isEmpty(events)){\r
-                events = Ext.isArray(events) ? events : Ext.toArray(arguments);\r
-                Ext.each(events, function(ename){\r
-                    ename = ename.toLowerCase();\r
-                    var ce = me.events[ename] || true;\r
-                    if (Ext.isBoolean(ce)) {\r
-                        ce = new Ext.util.Event(me, ename);\r
-                        me.events[ename] = ce;\r
-                    }\r
-                    ce.bubble = true;\r
-                });\r
-            }\r
-        }\r
-    };\r
-}());\r
-\r
-\r
-<div id="method-Ext.util.Observable-Observable.capture"></div>/**\r
- * Starts capture on the specified Observable. All events will be passed\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 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
-    o.fireEvent = o.fireEvent.createInterceptor(fn, scope);\r
-};\r
-\r
-\r
-<div id="method-Ext.util.Observable-Observable.observeClass"></div>/**\r
- * Sets observability on the passed class constructor.<p>\r
- * <p>This makes any event fired on any instance of the passed class also fire a single event through\r
- * the <i>class</i> allowing for central handling of events on many instances at once.</p>\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
-});</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
-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>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <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.2.1
+ * Copyright(c) 2006-2010 Ext JS, Inc.
+ * licensing@extjs.com
+ * http://www.extjs.com/license
+ */
+/**
+ * @class Ext.util.Observable
+ */
+Ext.apply(Ext.util.Observable.prototype, function(){
+    // this is considered experimental (along with beforeMethod, afterMethod, removeMethodListener?)
+    // allows for easier interceptor and sequences, including cancelling and overwriting the return value of the call
+    // private
+    function getMethodEvent(method){
+        var e = (this.methodEvents = this.methodEvents ||
+        {})[method], returnValue, v, cancel, obj = this;
+
+        if (!e) {
+            this.methodEvents[method] = e = {};
+            e.originalFn = this[method];
+            e.methodName = method;
+            e.before = [];
+            e.after = [];
+
+            var makeCall = function(fn, scope, args){
+                if((v = fn.apply(scope || obj, args)) !== undefined){
+                    if (typeof v == 'object') {
+                        if(v.returnValue !== undefined){
+                            returnValue = v.returnValue;
+                        }else{
+                            returnValue = v;
+                        }
+                        cancel = !!v.cancel;
+                    }
+                    else
+                        if (v === false) {
+                            cancel = true;
+                        }
+                        else {
+                            returnValue = v;
+                        }
+                }
+            };
+
+            this[method] = function(){
+                var args = Array.prototype.slice.call(arguments, 0),
+                    b;
+                returnValue = v = undefined;
+                cancel = false;
+
+                for(var i = 0, len = e.before.length; i < len; i++){
+                    b = e.before[i];
+                    makeCall(b.fn, b.scope, args);
+                    if (cancel) {
+                        return returnValue;
+                    }
+                }
+
+                if((v = e.originalFn.apply(obj, args)) !== undefined){
+                    returnValue = v;
+                }
+
+                for(var i = 0, len = e.after.length; i < len; i++){
+                    b = e.after[i];
+                    makeCall(b.fn, b.scope, args);
+                    if (cancel) {
+                        return returnValue;
+                    }
+                }
+                return returnValue;
+            };
+        }
+        return e;
+    }
+
+    return {
+        // these are considered experimental
+        // allows for easier interceptor and sequences, including cancelling and overwriting the return value of the call
+        // adds an 'interceptor' called before the original method
+        beforeMethod : function(method, fn, scope){
+            getMethodEvent.call(this, method).before.push({
+                fn: fn,
+                scope: scope
+            });
+        },
+
+        // adds a 'sequence' called after the original method
+        afterMethod : function(method, fn, scope){
+            getMethodEvent.call(this, method).after.push({
+                fn: fn,
+                scope: scope
+            });
+        },
+
+        removeMethodListener: function(method, fn, scope){
+            var e = this.getMethodEvent(method);
+            for(var i = 0, len = e.before.length; i < len; i++){
+                if(e.before[i].fn == fn && e.before[i].scope == scope){
+                    e.before.splice(i, 1);
+                    return;
+                }
+            }
+            for(var i = 0, len = e.after.length; i < len; i++){
+                if(e.after[i].fn == fn && e.after[i].scope == scope){
+                    e.after.splice(i, 1);
+                    return;
+                }
+            }
+        },
+
+        <div id="method-Ext.util.Observable-relayEvents"></div>/**
+         * Relays selected events from the specified Observable as if the events were fired by <tt><b>this</b></tt>.
+         * @param {Object} o The Observable whose events this object is to relay.
+         * @param {Array} events Array of event names to relay.
+         */
+        relayEvents : function(o, events){
+            var me = this;
+            function createHandler(ename){
+                return function(){
+                    return me.fireEvent.apply(me, [ename].concat(Array.prototype.slice.call(arguments, 0)));
+                };
+            }
+            for(var i = 0, len = events.length; i < len; i++){
+                var ename = events[i];
+                me.events[ename] = me.events[ename] || true;
+                o.on(ename, createHandler(ename), me);
+            }
+        },
+
+        <div id="method-Ext.util.Observable-enableBubble"></div>/**
+         * <p>Enables events fired by this Observable to bubble up an owner hierarchy by calling
+         * <code>this.getBubbleTarget()</code> if present. There is no implementation in the Observable base class.</p>
+         * <p>This is commonly used by Ext.Components to bubble events to owner Containers. See {@link Ext.Component.getBubbleTarget}. The default
+         * implementation in Ext.Component returns the Component's immediate owner. But if a known target is required, this can be overridden to
+         * access the required target more quickly.</p>
+         * <p>Example:</p><pre><code>
+Ext.override(Ext.form.Field, {
+    //  Add functionality to Field&#39;s initComponent to enable the change event to bubble
+    initComponent : Ext.form.Field.prototype.initComponent.createSequence(function() {
+        this.enableBubble('change');
+    }),
+
+    //  We know that we want Field&#39;s events to bubble directly to the FormPanel.
+    getBubbleTarget : function() {
+        if (!this.formPanel) {
+            this.formPanel = this.findParentByType('form');
+        }
+        return this.formPanel;
+    }
+});
+
+var myForm = new Ext.formPanel({
+    title: 'User Details',
+    items: [{
+        ...
+    }],
+    listeners: {
+        change: function() {
+            // Title goes red if form has been modified.
+            myForm.header.setStyle('color', 'red');
+        }
+    }
+});
+</code></pre>
+         * @param {String/Array} events The event name to bubble, or an Array of event names.
+         */
+        enableBubble : function(events){
+            var me = this;
+            if(!Ext.isEmpty(events)){
+                events = Ext.isArray(events) ? events : Array.prototype.slice.call(arguments, 0);
+                for(var i = 0, len = events.length; i < len; i++){
+                    var ename = events[i];
+                    ename = ename.toLowerCase();
+                    var ce = me.events[ename] || true;
+                    if (typeof ce == 'boolean') {
+                        ce = new Ext.util.Event(me, ename);
+                        me.events[ename] = ce;
+                    }
+                    ce.bubble = true;
+                }
+            }
+        }
+    };
+}());
+
+
+<div id="method-Ext.util.Observable-Observable.capture"></div>/**
+ * Starts capture on the specified Observable. All events will be passed
+ * to the supplied function with the event name + standard signature of the event
+ * <b>before</b> the event is fired. If the supplied function returns false,
+ * the event will not fire.
+ * @param {Observable} o The Observable to capture events from.
+ * @param {Function} fn The function to call when an event is fired.
+ * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the function is executed. Defaults to the Observable firing the event.
+ * @static
+ */
+Ext.util.Observable.capture = function(o, fn, scope){
+    o.fireEvent = o.fireEvent.createInterceptor(fn, scope);
+};
+
+
+<div id="method-Ext.util.Observable-Observable.observeClass"></div>/**
+ * Sets observability on the passed class constructor.<p>
+ * <p>This makes any event fired on any instance of the passed class also fire a single event through
+ * the <i>class</i> allowing for central handling of events on many instances at once.</p>
+ * <p>Usage:</p><pre><code>
+Ext.util.Observable.observeClass(Ext.data.Connection);
+Ext.data.Connection.on('beforerequest', function(con, options) {
+    console.log('Ajax request made to ' + options.url);
+});</code></pre>
+ * @param {Function} c The class constructor to make observable.
+ * @param {Object} listeners An object containing a series of listeners to add. See {@link #addListener}.
+ * @static
+ */
+Ext.util.Observable.observeClass = function(c, listeners){
+    if(c){
+      if(!c.fireEvent){
+          Ext.apply(c, new Ext.util.Observable());
+          Ext.util.Observable.capture(c.prototype, c.fireEvent, c);
+      }
+      if(typeof listeners == 'object'){
+          c.on(listeners);
+      }
+      return c;
+   }
+};
+</pre>    
+</body>
 </html>
\ No newline at end of file