~testplan-team/testplan/source-collection

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.

#### Options: {#Function:create:options}

* bind - (*object*: defaults to this function) The object that the "this" of the function will refer to.

* 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.

* 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.

* 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.

* 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.

* attempt - (*boolean*: false) If set to true, the returned function will try to execute and return either the results or null on error.

### Returns:

* (*function*) The function that was created as a result of the options passed in.

### Example:

var myFunction = function(){

alert("I'm a function. :D");

};

var mySimpleFunction = myFunction.create(); //Just a simple copy.

var myAdvancedFunction = myFunction.create({ //When called, this function will attempt.

arguments: [0,1,2,3],

attempt: true,

delay: 1000,

bind: myElement

});

Function Method: pass {#Function:pass}

--------------------------------------

Returns a closure with arguments and bind.

### Syntax:

var newFunction = myFunction.pass([args[, bind]]);

### Arguments:

1. args - (*mixed*, optional) The arguments to pass to the function (must be an array if passing more than one argument).

2. bind - (*object*, optional) The object that the "this" of the function will refer to.

### Returns:

* (*function*) The function whose arguments are passed when called.

### Example:

var myFunction = function(){

var result = 'Passed: ';

for (var i = 0, l = arguments.length; i < l; i++){

result += (arguments[i] + ' ');

}

return result;

}

var myHello = myFunction.pass('hello');

var myItems = myFunction.pass(['peach', 'apple', 'orange']);

//Later in the code, the functions can be executed:

alert(myHello()); //Passes "hello" to myFunction.

alert(myItems()); //Passes the array of items to myFunction.

Function Method: attempt {#Function:attempt}

--------------------------------------------

Tries to execute the function.

### Syntax:

var result = myFunction.attempt([args[, bind]]);

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

function myFunction(e, add){

176

//Note that 'this' here refers to window, not an element.

177

//We'll need to bind this function to the element we want to alter.

178

this.setStyle('top', e.client.x + add);

179

};

180

$(myElement).addEvent('click', myFunction.bindWithEvent(myElement, 100));

181

//When clicked, the element will move to the position of the mouse + 100.

182

183

184

185

Function Method: delay {#Function:delay}

186

----------------------------------------

187

188

Delays the execution of a function by a specified duration.

189

190

### Syntax:

191

192

var timeoutID = myFunction.delay(delay[, bind[, args]]);

193

194

### Arguments:

195

196

1. delay - (*number*) The duration to wait (in milliseconds).

197

2. bind - (*object*, optional) The object that the "this" of the function will refer to.

198

3. args - (*mixed*, optional) The arguments passed (must be an array if the arguments are greater than one).

199

200

### Returns:

201

202

* (*number*) The JavaScript timeout id (for clearing delays).

203

204

### Example:

205

206

var myFunction = function(){ alert('moo! Element id is: ' + this.id); };

207

//Wait 50 milliseconds, then call myFunction and bind myElement to it.

208

myFunction.delay(50, myElement); //Alerts: 'moo! Element id is: ... '

209

210

//An anonymous function which waits a second and then alerts.

211

(function(){ alert('one second later...'); }).delay(1000);

212

213

214

### See Also:

215

216

- [$clear][], [MDC setTimeout][]

217

218

219

220

Function Method: periodical {#Function:periodical}

221

--------------------------------------------------

222

223

Executes a function in the specified intervals of time. Periodic execution can be stopped using the [$clear][] function.

224

225

### Syntax:

226

227

var intervalID = myFunction.periodical(period[, bind[, args]]);

228

229

### Arguments:

230

231

1. period - (*number*) The duration of the intervals between executions.

232

2. bind - (*object*, optional) The object that the "this" of the function will refer to.

233

3. args - (*mixed*, optional) The arguments passed (must be an array if the arguments are greater than one).

234

235

### Returns:

236

237

* (*number*) The Interval id (for clearing a periodical).

238

239

### Example:

240

241

var Site = { counter: 0 };

242

var addCount = function(){ this.counter++; };

243

addCount.periodical(1000, Site); //Will add the number of seconds at the Site.

244

245

246

### See Also:

247

248

- [$clear][], [MDC setInterval][]

249

250

251

252

Function Method: run {#Function:run}

253

------------------------------------

254

255

Runs the Function with specified arguments and binding. The same as apply but reversed and with support for a single argument.

256

257

### Syntax:

258

259

var myFunctionResult = myFunction.run(args[, bind]);

260

261

### Arguments:

262

263

1. args - (*mixed*) An argument, or array of arguments to run the function with.

264

2. bind - (*object*, optional) The object that the "this" of the function will refer to.

265

266

### Returns:

267

268

* (*mixed*) This Function's return value.

269

270

### Examples:

271

272

#### Simple Run:

273

274

var myFn = function(a, b, c){

275

return a + b + c;

276

}

277

var myArgs = [1,2,3];

278

myFn.run(myArgs); //Returns: 6

279

280

281

#### Run With Binding:

282

283

var myFn = function(a, b, c) {

284

return a + b + c + this;

285

}

286

var myArgs = [1,2,3];

287

myFn.run(myArgs, 6); //Returns: 12

288

289

290

291

[options]: #Function:create:options

292

[Element:addEvent]: /Element/Element.Event/#Element:addEvent

293

[$clear]: /Core/Core/#clear

294

[MDC Function]: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Function

295

[MDC setInterval]: http://developer.mozilla.org/en/docs/DOM:window.setInterval

296

[MDC setTimeout]: http://developer.mozilla.org/en/docs/DOM:window.setTimeout

b'\\ No newline at end of file'

Older »