Docs/Native/Function.md

   1 Native: Function {#Function}
   2 ============================
   3
   4 Function Methods.
   5
   6 ### See Also:
   7
   8 - [MDC Function][]
   9
  10
  11
  12 Function Method: create {#Function:create}
  13 ------------------------------------------
  14
  15 Base function for creating functional closures which is used by all other Function prototypes.
  16
  17 ### Syntax:
  18
  19         var createdFunction = myFunction.create([options]);
  20
  21 ### Arguments:
  22
  23 1. [options] - (*object*, optional) The options from which the function will be created. If options is not provided, then creates a copy of the function.
  24
  25 #### Options: {#Function:create:options}
  26
  27 * bind       - (*object*: defaults to this function) The object that the "this" of the function will refer to.
  28 * event      - (*mixed*: defaults to false) If set to true, the function will act as an event listener and receive an event as its first argument. If set to a class name, the function will receive a new instance of this class (with the event passed as argument's constructor) as first argument.
  29 * arguments  - (*mixed*: defaults to standard arguments) A single argument or an array of arguments that will be passed as arguments to the function. If both the event and arguments options are set, the event is passed as first argument and the arguments array will follow.
  30 * delay      - (*number*: defaults to no delay) If set, the returned function will delay the actual execution by this amount of milliseconds and return a timer handle when called.
  31 * periodical - (*number*: defaults to no periodical execution) If set, the returned function will periodically perform the actual execution with this specified interval and return a timer handle when called.
  32 * attempt    - (*boolean*: false) If set to true, the returned function will try to execute and return either the results or null on error.
  33
  34 ### Returns:
  35
  36 * (*function*) The function that was created as a result of the options passed in.
  37
  38 ### Example:
  39
  40         var myFunction = function(){
  41                 alert("I'm a function. :D");
  42         };
  43
  44         var mySimpleFunction = myFunction.create(); //Just a simple copy.
  45
  46         var myAdvancedFunction = myFunction.create({ //When called, this function will attempt.
  47                 arguments: [0,1,2,3],
  48                 attempt: true,
  49                 delay: 1000,
  50                 bind: myElement
  51         });
  52
  53
  54
  55 Function Method: pass {#Function:pass}
  56 --------------------------------------
  57
  58 Returns a closure with arguments and bind.
  59
  60 ### Syntax:
  61
  62         var newFunction = myFunction.pass([args[, bind]]);
  63
  64 ### Arguments:
  65
  66 1. args - (*mixed*, optional) The arguments to pass to the function (must be an array if passing more than one argument).
  67 2. bind - (*object*, optional) The object that the "this" of the function will refer to.
  68
  69 ### Returns:
  70
  71 * (*function*) The function whose arguments are passed when called.
  72
  73 ### Example:
  74
  75         var myFunction = function(){
  76                 var result = 'Passed: ';
  77                 for (var i = 0, l = arguments.length; i < l; i++){
  78                         result += (arguments[i] + ' ');
  79                 }
  80                 return result;
  81         }
  82         var myHello = myFunction.pass('hello');
  83         var myItems = myFunction.pass(['peach', 'apple', 'orange']);
  84
  85         //Later in the code, the functions can be executed:
  86         alert(myHello()); //Passes "hello" to myFunction.
  87         alert(myItems()); //Passes the array of items to myFunction.
  88
  89
  90
  91 Function Method: attempt {#Function:attempt}
  92 --------------------------------------------
  93
  94 Tries to execute the function.
  95
  96 ### Syntax:
  97
  98         var result = myFunction.attempt([args[, bind]]);
  99
 100 ### Arguments:
 101
 102 1. args - (*mixed*, optional) The arguments to pass to the function (must be an array if passing more than one argument).
 103 2. bind - (*object*, optional) The object that the "this" of the function will refer to.
 104
 105 ### Returns:
 106
 107 * (*mixed*) The function's return value or `null` if an exception is thrown.
 108
 109 ### Example:
 110
 111         var myObject = {
 112                 'cow': 'moo!'
 113         };
 114
 115         var myFunction = function(){
 116                 for (var i = 0; i < arguments.length; i++){
 117                         if(!this[arguments[i]]) throw('doh!');
 118                 }
 119         };
 120         var result = myFunction.attempt(['pig', 'cow'], myObject); //result = null
 121
 122
 123
 124 Function Method: bind {#Function:bind}
 125 --------------------------------------
 126
 127 Changes the scope of `this` within the target function to refer to the bind parameter.
 128
 129 ### Syntax:
 130
 131         myFunction.bind([bind[, args[, evt]]]);
 132
 133 ### Arguments:
 134
 135 1. bind - (*object*, optional) The object that the "this" of the function will refer to.
 136 2. args - (*mixed*, optional) The arguments to pass to the function (must be an array if passing more than one argument).
 137
 138 ### Returns:
 139
 140 * (*function*) The bound function.
 141
 142 ### Example:
 143
 144         function myFunction(){
 145                 //Note that 'this' here refers to window, not an element.
 146                 //The function must be bound to the element we want to manipulate.
 147                 this.setStyle('color', 'red');
 148         };
 149         var myBoundFunction = myFunction.bind(myElement);
 150         myBoundFunction(); //This will make myElement's text red.
 151
 152
 153
 154 Function Method: bindWithEvent {#Function:bindWithEvent}
 155 --------------------------------------------------------
 156
 157 Changes the scope of `this` within the target function to refer to the bind parameter. It also makes "space" for an event.
 158 This allows the function to be used in conjunction with [Element:addEvent][] and arguments.
 159
 160 ### Syntax:
 161
 162         myFunction.bindWithEvent([bind[, args[, evt]]]);
 163
 164 ### Arguments:
 165
 166 1. bind - (*object*, optional) The object that the "this" of the function will refer to.
 167 2. args - (*mixed*, optional) The arguments to pass to the function (must be an array if passing more than one argument).
 168
 169 ### Returns:
 170
 171 * (*function*) The bound function.
 172
 173 ### Example:
 174
 175     var Logger = new Class({
 176         log: function(){
 177             console.log.apply(null, arguments);
 178         }
 179     });
 180
 181     var Log = new Logger();
 182
 183         $('myElement').addEvent('click', function(event, offset){
 184             offset += event.client.x;
 185             this.log('clicked; moving to:', offset); // this refers to myClass
 186             event.target.setStyle('top', offset);
 187             return false;
 188         }).bindWithEvent(Log, 100));
 189
 190
 191 Function Method: delay {#Function:delay}
 192 ----------------------------------------
 193
 194 Delays the execution of a function by a specified duration.
 195
 196 ### Syntax:
 197
 198         var timeoutID = myFunction.delay(delay[, bind[, args]]);
 199
 200 ### Arguments:
 201
 202 1. delay - (*number*) The duration to wait (in milliseconds).
 203 2. bind  - (*object*, optional) The object that the "this" of the function will refer to.
 204 3. args  - (*mixed*, optional) The arguments passed (must be an array if the arguments are greater than one).
 205
 206 ### Returns:
 207
 208 * (*number*) The JavaScript timeout id (for clearing delays).
 209
 210 ### Example:
 211
 212         var myFunction = function(){ alert('moo! Element id is: ' + this.id); };
 213         //Wait 50 milliseconds, then call myFunction and bind myElement to it.
 214         myFunction.delay(50, myElement); //Alerts: 'moo! Element id is: ... '
 215
 216         //An anonymous function which waits a second and then alerts.
 217         (function(){ alert('one second later...'); }).delay(1000);
 218
 219
 220 ### See Also:
 221
 222 - [$clear][], [MDC setTimeout][]
 223
 224
 225
 226 Function Method: periodical {#Function:periodical}
 227 --------------------------------------------------
 228
 229 Executes a function in the specified intervals of time. Periodic execution can be stopped using the [$clear][] function.
 230
 231 ### Syntax:
 232
 233         var intervalID = myFunction.periodical(period[, bind[, args]]);
 234
 235 ### Arguments:
 236
 237 1. period - (*number*) The duration of the intervals between executions.
 238 2. bind   - (*object*, optional) The object that the "this" of the function will refer to.
 239 3. args   - (*mixed*, optional) The arguments passed (must be an array if the arguments are greater than one).
 240
 241 ### Returns:
 242
 243 * (*number*) The Interval id (for clearing a periodical).
 244
 245 ### Example:
 246
 247         var Site = { counter: 0 };
 248         var addCount = function(){ this.counter++; };
 249         addCount.periodical(1000, Site); //Will add the number of seconds at the Site.
 250
 251
 252 ### See Also:
 253
 254 - [$clear][], [MDC setInterval][]
 255
 256
 257
 258 Function Method: run {#Function:run}
 259 ------------------------------------
 260
 261 Runs the Function with specified arguments and binding. The same as apply but reversed and with support for a single argument.
 262
 263 ### Syntax:
 264
 265         var myFunctionResult = myFunction.run(args[, bind]);
 266
 267 ### Arguments:
 268
 269 1. args - (*mixed*) An argument, or array of arguments to run the function with.
 270 2. bind - (*object*, optional) The object that the "this" of the function will refer to.
 271
 272 ### Returns:
 273
 274 * (*mixed*) This Function's return value.
 275
 276 ### Examples:
 277
 278 #### Simple Run:
 279
 280         var myFn = function(a, b, c){
 281                 return a + b + c;
 282         }
 283         var myArgs = [1,2,3];
 284         myFn.run(myArgs); //Returns: 6
 285
 286
 287 #### Run With Binding:
 288
 289         var myFn = function(a, b, c) {
 290                 return a + b + c + this;
 291         }
 292         var myArgs = [1,2,3];
 293         myFn.run(myArgs, 6); //Returns: 12
 294
 295
 296
 297 [options]: #Function:create:options
 298 [Element:addEvent]: /core/Element/Element.Event/#Element:addEvent
 299 [$clear]: /core/Core/Core/#clear
 300 [MDC Function]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Function
 301 [MDC setInterval]: http://developer.mozilla.org/en/docs/DOM:window.setInterval
 302 [MDC setTimeout]: http://developer.mozilla.org/en/docs/DOM:window.setTimeout