Native/Function.js

   1 /*
   2 Script: Function.js
   3         Contains Function prototypes, utility functions and Chain.
   4
   5 Dependencies:
   6         <Moo.js>
   7
   8 Author:
   9         Valerio Proietti, <http://mad4milk.net>
  10
  11 License:
  12         MIT-style license.
  13
  14 Credits:
  15         - Some functions are inspired by those found in prototype.js <http://prototype.conio.net/> (c) 2005 Sam Stephenson sam [at] conio [dot] net, MIT-style license
  16 */
  17
  18 /*
  19 Class: Function
  20         A collection of The Function Object prototype methods.
  21 */
  22
  23 Function.extend({
  24
  25         /*
  26         Property: pass
  27                 Shortcut to create closures with arguments and bind.
  28
  29         Returns:
  30                 a function.
  31
  32         Arguments:
  33                 args - the arguments to pass to that function (array or single variable)
  34                 bind - optional, the object that the "this" of the function will refer to.
  35
  36         Example:
  37                 >myFunction.pass([arg1, arg2], myElement);
  38         */
  39
  40         pass: function(args, bind){
  41                 var fn = this;
  42                 if ($type(args) != 'array') args = [args];
  43                 return function(){
  44                         return fn.apply(bind || fn._proto_ || fn, args);
  45                 };
  46         },
  47
  48         /*
  49         Property: bind
  50                 method to easily create closures with "this" altered.
  51
  52         Arguments:
  53                 bind - optional, the object that the "this" of the function will refer to.
  54
  55         Returns:
  56                 a function.
  57
  58         Example:
  59                 >function myFunction(){
  60                 >       this.setStyle('color', 'red');
  61                 >       // note that 'this' here refers to myFunction, not an element
  62                 >       // we'll need to bind this function to the element we want to alter
  63                 >};
  64                 >var myBoundFunction = myFunction.bind(myElement);
  65                 >myBoundFunction(); // this will make the element myElement red.
  66         */
  67
  68         bind: function(bind){
  69                 var fn = this;
  70                 return function(){
  71                         return fn.apply(bind, arguments);
  72                 };
  73         },
  74
  75         /*
  76         Property: bindAsEventListener
  77                 cross browser method to pass event firer
  78
  79         Arguments:
  80                 bind - optional, the object that the "this" of the function will refer to.
  81
  82         Returns:
  83                 a function with the parameter bind as its "this" and as a pre-passed argument event or window.event, depending on the browser.
  84
  85         Example:
  86                 >function myFunction(event){
  87                 >       alert(event.clientx) //returns the coordinates of the mouse..
  88                 >};
  89                 >myElement.onclick = myFunction.bindAsEventListener(myElement);
  90         */
  91
  92         bindAsEventListener: function(bind){
  93                 var fn = this;
  94                 return function(event){
  95                         fn.call(bind, event || window.event);
  96                         return false;
  97                 };
  98         },
  99
 100         /*
 101         Property: delay
 102                 Delays the execution of a function by a specified duration.
 103
 104         Arguments:
 105                 ms - the duration to wait in milliseconds
 106                 bind - optional, the object that the "this" of the function will refer to.
 107
 108         Example:
 109                 >myFunction.delay(50, myElement) //wait 50 milliseconds, then call myFunction and bind myElement to it
 110                 >(function(){alert('one second later...')}).delay(1000); //wait a second and alert
 111         */
 112
 113         delay: function(ms, bind){
 114                 return setTimeout(this.bind(bind || this._proto_ || this), ms);
 115         },
 116
 117         /*
 118         Property: periodical
 119                 Executes a function in the specified intervals of time
 120
 121         Arguments:
 122                 ms - the duration of the intervals between executions.
 123                 bind - optional, the object that the "this" of the function will refer to.
 124         */
 125
 126         periodical: function(ms, bind){
 127                 return setInterval(this.bind(bind || this._proto_ || this), ms);
 128         }
 129
 130 });
 131
 132 /* Section: Utility Functions  */
 133
 134 /*
 135 Function: $clear
 136         clears a timeout or an Interval.
 137
 138 Returns:
 139         null
 140
 141 Arguments:
 142         timer - the setInterval or setTimeout to clear.
 143
 144 Example:
 145         >var myTimer = myFunction.delay(5000); //wait 5 seconds and execute my function.
 146         >myTimer = $clear(myTimer); //nevermind
 147
 148 See also:
 149         <Function.delay>, <Function.periodical>
 150 */
 151
 152 function $clear(timer){
 153         clearTimeout(timer);
 154         clearInterval(timer);
 155         return null;
 156 };
 157
 158 /*
 159 Function: $type
 160         Returns the type of object that matches the element passed in.
 161
 162 Arguments:
 163         obj - the object to inspect.
 164
 165 Example:
 166         >var myString = 'hello';
 167         >$type(myString); //returns "string"
 168
 169 Returns:
 170         'function' - if obj is a function
 171         'textnode' - if obj is a node but not an element
 172         'element' - if obj is a DOM element
 173         'array' - if obj is an array
 174         'object' - if obj is an object
 175         'string' - if obj is a string
 176         'number' - if obj is a number
 177         false - (boolean) if the object is not defined or none of the above, or if it's an empty string.
 178 */
 179
 180 function $type(obj){
 181         if (!obj) return false;
 182         var type = false;
 183         if (obj instanceof Function) type = 'function';
 184         else if (obj.nodeName){
 185                 if (obj.nodeType == 3 && !/\S/.test(obj.nodeValue)) type = 'textnode';
 186                 else if (obj.nodeType == 1) type = 'element';
 187         }
 188         else if (obj instanceof Array) type = 'array';
 189         else if (typeof obj == 'object') type = 'object';
 190         else if (typeof obj == 'string') type = 'string';
 191         else if (typeof obj == 'number' && isFinite(obj)) type = 'number';
 192         return type;
 193 };
 194
 195 /*Class: Chain*/
 196
 197 var Chain = new Class({
 198
 199         /*
 200         Property: chain
 201                 adds a function to the Chain instance stack.
 202
 203         Arguments:
 204                 fn - the function to append.
 205
 206         Returns:
 207                 the instance of the <Chain> class.
 208
 209         Example:
 210                 >var myChain = new Chain();
 211                 >myChain.chain(myFunction).chain(myFunction2);
 212         */
 213
 214         chain: function(fn){
 215                 this.chains = this.chains || [];
 216                 this.chains.push(fn);
 217                 return this;
 218         },
 219
 220         /*
 221         Property: callChain
 222                 Executes the first function of the Chain instance stack, then removes it. The first function will then become the second.
 223
 224         Example:
 225                 >myChain.callChain(); //executes myFunction
 226                 >myChain.callChain(); //executes myFunction2
 227         */
 228
 229         callChain: function(){
 230                 if (this.chains && this.chains.length) this.chains.splice(0, 1)[0].delay(10, this);
 231         },
 232
 233         /*
 234         Property: clearChain
 235                 Clears the stack of a Chain instance.
 236         */
 237
 238         clearChain: function(){
 239                 this.chains = [];
 240         }
 241
 242 });