-
Notifications
You must be signed in to change notification settings - Fork 491
/
Signal.js
502 lines (442 loc) · 16.2 KB
/
Signal.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
/**
* @author Miller Medeiros http://millermedeiros.github.com/js-signals/
* @author Richard Davey <rich@photonstorm.com>
* @copyright 2016 Photon Storm Ltd.
* @license {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
*/
/**
* Signals are what Phaser uses to handle events and event dispatching.
* You can listen for a Signal by binding a callback / function to it.
* This is done by using either `Signal.add` or `Signal.addOnce`.
*
* For example you can listen for a touch or click event from the Input Manager
* by using its `onDown` Signal:
*
* `game.input.onDown.add(function() { ... });`
*
* Rather than inline your function, you can pass a reference:
*
* `game.input.onDown.add(clicked, this);`
* `function clicked () { ... }`
*
* In this case the second argument (`this`) is the context in which your function should be called.
*
* Now every time the InputManager dispatches the `onDown` signal (or event), your function
* will be called.
*
* Multiple callbacks can be bound to the same signal.
* They're ordered first by their `priority` arguments and then by the order in which they were added.
* If a callback calls {@link #halt} or returns `false`, any remaining callbacks are skipped.
*
* Very often a Signal will send arguments to your function.
* This is specific to the Signal itself.
* If you're unsure then check the documentation, or failing that simply do:
*
* `Signal.add(function() { console.log(arguments); })`
*
* and it will log all of the arguments your function received from the Signal.
*
* Sprites have lots of default signals you can listen to in their Events class, such as:
*
* `sprite.events.onKilled`
*
* Which is called automatically whenever the Sprite is killed.
* There are lots of other events, see the Events component for a list.
*
* As well as listening to pre-defined Signals you can also create your own:
*
* `var mySignal = new Phaser.Signal();`
*
* This creates a new Signal. You can bind a callback to it:
*
* `mySignal.add(myCallback, this);`
*
* and then finally when ready you can dispatch the Signal:
*
* `mySignal.dispatch(your arguments);`
*
* And your callback will be invoked. See the dispatch method for more details.
*
* @class Phaser.Signal
* @constructor
*/
Phaser.Signal = function () {};
Phaser.Signal.prototype = {
/**
* @property {?Array.<Phaser.SignalBinding>} _bindings - Internal variable.
* @private
*/
_bindings: null,
/**
* @property {any} _prevParams - Internal variable.
* @private
*/
_prevParams: null,
/**
* Memorize the previously dispatched event?
*
* If an event has been memorized it is automatically dispatched when a new listener is added with {@link #add} or {@link #addOnce}.
* Use {@link #forget} to clear any currently memorized event.
*
* @property {boolean} memorize
*/
memorize: false,
/**
* @property {boolean} _shouldPropagate
* @private
*/
_shouldPropagate: true,
/**
* Is the Signal active? Only active signals will broadcast dispatched events.
*
* Setting this property during a dispatch will only affect the next dispatch. To stop the propagation of a signal from a listener use {@link #halt}.
*
* @property {boolean} active
* @default
*/
active: true,
/**
* @property {function} _boundDispatch - The bound dispatch function, if any.
* @private
*/
_boundDispatch: false,
/**
* @method Phaser.Signal#validateListener
* @param {function} listener - Signal handler function.
* @param {string} fnName - Function name.
* @private
*/
validateListener: function (listener, fnName)
{
if (typeof listener !== 'function')
{
throw new Error('Phaser.Signal: listener is a required param of {fn}() and should be a Function.'.replace('{fn}', fnName));
}
},
/**
* @method Phaser.Signal#_registerListener
* @private
* @param {function} listener - Signal handler function.
* @param {boolean} isOnce - Should the listener only be called once?
* @param {object} [listenerContext] - The context under which the listener is invoked.
* @param {number} [priority] - The priority level of the event listener. Listeners with higher priority will be executed before listeners with lower priority. Listeners with same priority level will be executed at the same order as they were added. (default = 0).
* @return {Phaser.SignalBinding} An Object representing the binding between the Signal and listener.
*/
_registerListener: function (listener, isOnce, listenerContext, priority, args)
{
var prevIndex = this._indexOfListener(listener, listenerContext);
var binding;
if (prevIndex !== -1)
{
binding = this._bindings[prevIndex];
if (binding.isOnce() !== isOnce)
{
throw new Error('You cannot add' + (isOnce ? '' : 'Once') + '() then add' + (!isOnce ? '' : 'Once') + '() the same listener without removing the relationship first.');
}
}
else
{
binding = new Phaser.SignalBinding(this, listener, isOnce, listenerContext, priority, args);
this._addBinding(binding);
}
if (this.memorize && this._prevParams)
{
binding.execute(this._prevParams);
}
return binding;
},
/**
* @method Phaser.Signal#_addBinding
* @private
* @param {Phaser.SignalBinding} binding - An Object representing the binding between the Signal and listener.
*/
_addBinding: function (binding)
{
if (!this._bindings)
{
this._bindings = [];
}
// Simplified insertion sort
var n = this._bindings.length;
do
{
n--;
}
while (this._bindings[n] && binding._priority <= this._bindings[n]._priority);
this._bindings.splice(n + 1, 0, binding);
},
/**
* @method Phaser.Signal#_indexOfListener
* @private
* @param {function} listener - Signal handler function.
* @param {object} [context=null] - Signal handler function.
* @return {number} The index of the listener within the private bindings array.
*/
_indexOfListener: function (listener, context)
{
if (!this._bindings)
{
return -1;
}
if (context === undefined) { context = null; }
var n = this._bindings.length;
var cur;
while (n--)
{
cur = this._bindings[n];
if (cur._listener === listener && cur.context === context)
{
return n;
}
}
return -1;
},
/**
* Check if a specific listener is attached.
*
* @method Phaser.Signal#has
* @param {function} listener - Signal handler function.
* @param {object} [context] - Context on which listener will be executed (object that should represent the `this` variable inside listener function).
* @return {boolean} If Signal has the specified listener.
*/
has: function (listener, context)
{
return this._indexOfListener(listener, context) !== -1;
},
/**
* Add an event listener for this signal.
*
* An event listener is a callback with a related context and priority.
*
* You can optionally provide extra arguments which will be passed to the callback after any internal parameters.
*
* For example: `Phaser.Key.onDown` when dispatched will send the Phaser.Key object that caused the signal as the first parameter.
* Any arguments you've specified after `priority` will be sent as well:
*
* `fireButton.onDown.add(shoot, this, 0, 'lazer', 100);`
*
* When onDown dispatches it will call the `shoot` callback passing it: `Phaser.Key, 'lazer', 100`.
*
* Where the first parameter is the one that Key.onDown dispatches internally and 'lazer',
* and the value 100 were the custom arguments given in the call to 'add'.
*
* If the callback calls {@link #halt} or returns `false`, any remaining callbacks bound to this Signal are skipped.
*
* @method Phaser.Signal#add
* @param {function} listener - The function to call when this Signal is dispatched.
* @param {object} [listenerContext] - The context under which the listener will be executed (i.e. the object that should represent the `this` variable).
* @param {number} [priority] - The priority level of the event listener. Listeners with higher priority will be executed before listeners with lower priority. Listeners with same priority level will be executed at the same order as they were added (default = 0)
* @param {...any} [args=(none)] - Additional arguments to pass to the callback (listener) function. They will be appended after any arguments usually dispatched.
* @return {Phaser.SignalBinding} An Object representing the binding between the Signal and listener.
*/
add: function (listener, listenerContext, priority)
{
this.validateListener(listener, 'add');
var args = [];
if (arguments.length > 3)
{
for (var i = 3; i < arguments.length; i++)
{
args.push(arguments[i]);
}
}
return this._registerListener(listener, false, listenerContext, priority, args);
},
/**
* Add a one-time listener - the listener is automatically removed after the first execution.
*
* If there is as {@link Phaser.Signal#memorize memorized} event then it will be dispatched and
* the listener will be removed immediately.
*
* @method Phaser.Signal#addOnce
* @param {function} listener - The function to call when this Signal is dispatched.
* @param {object} [listenerContext] - The context under which the listener will be executed (i.e. the object that should represent the `this` variable).
* @param {number} [priority] - The priority level of the event listener. Listeners with higher priority will be executed before listeners with lower priority. Listeners with same priority level will be executed at the same order as they were added (default = 0)
* @param {...any} [args=(none)] - Additional arguments to pass to the callback (listener) function. They will be appended after any arguments usually dispatched.
* @return {Phaser.SignalBinding} An Object representing the binding between the Signal and listener.
*/
addOnce: function (listener, listenerContext, priority)
{
this.validateListener(listener, 'addOnce');
var args = [];
if (arguments.length > 3)
{
for (var i = 3; i < arguments.length; i++)
{
args.push(arguments[i]);
}
}
return this._registerListener(listener, true, listenerContext, priority, args);
},
/**
* Remove a single event listener.
*
* @method Phaser.Signal#remove
* @param {function} listener - Handler function that should be removed.
* @param {object} [context=null] - Execution context (since you can add the same handler multiple times if executing in a different context).
* @return {function} Listener handler function.
*/
remove: function (listener, context)
{
this.validateListener(listener, 'remove');
var i = this._indexOfListener(listener, context);
if (i !== -1)
{
this._bindings[i]._destroy(); // no reason to a Phaser.SignalBinding exist if it isn't attached to a signal
this._bindings.splice(i, 1);
}
return listener;
},
/**
* Remove all event listeners.
*
* @method Phaser.Signal#removeAll
* @param {object} [context=null] - If specified only listeners for the given context will be removed.
*/
removeAll: function (context)
{
if (context === undefined) { context = null; }
if (!this._bindings)
{
return;
}
var n = this._bindings.length;
while (n--)
{
if (context)
{
if (this._bindings[n].context === context)
{
this._bindings[n]._destroy();
this._bindings.splice(n, 1);
}
}
else
{
this._bindings[n]._destroy();
}
}
if (!context)
{
this._bindings.length = 0;
}
},
/**
* Gets the total number of listeners attached to this Signal.
*
* @method Phaser.Signal#getNumListeners
* @return {integer} Number of listeners attached to the Signal.
*/
getNumListeners: function ()
{
return this._bindings ? this._bindings.length : 0;
},
/**
* Stop propagation of the event, blocking the dispatch to next listener on the queue.
*
* This should be called only during event dispatch as calling it before/after dispatch won't affect another broadcast.
* See {@link #active} to enable/disable the signal entirely.
*
* @method Phaser.Signal#halt
*/
halt: function ()
{
this._shouldPropagate = false;
},
/**
* Dispatch / broadcast the event to all listeners.
*
* To create an instance-bound dispatch for this Signal, use {@link #boundDispatch}.
*
* @method Phaser.Signal#dispatch
* @param {any} [params] - Parameters that should be passed to each handler.
*/
dispatch: function ()
{
if (!this.active || (!this._bindings && !this.memorize))
{
return;
}
var paramsArr = Array.prototype.slice.call(arguments);
if (this.memorize)
{
this._prevParams = paramsArr;
}
var n = this._bindings ? this._bindings.length : 0;
if (!n)
{
// Should come after memorize
return;
}
var bindings = this._bindings.slice(); // clone array in case add/remove items during dispatch
this._shouldPropagate = true; // in case `halt` was called before dispatch or during the previous dispatch.
/*
* execute all callbacks until end of the list or until a callback returns `false` or stops propagation
* reverse loop since listeners with higher priority will be added at the end of the list
*/
do
{
n--;
}
while (bindings[n] && this._shouldPropagate && bindings[n].execute(paramsArr) !== false);
},
/**
* Forget the currently {@link Phaser.Signal#memorize memorized} event, if any.
*
* @method Phaser.Signal#forget
*/
forget: function ()
{
if (this._prevParams)
{
this._prevParams = null;
}
},
/**
* Dispose the signal - no more events can be dispatched.
*
* This removes all event listeners and clears references to external objects.
* Calling methods on a disposed objects results in undefined behavior.
*
* @method Phaser.Signal#dispose
*/
dispose: function ()
{
this.removeAll();
this._bindings = null;
if (this._prevParams)
{
this._prevParams = null;
}
},
/**
* A string representation of the object.
*
* @method Phaser.Signal#toString
* @return {string} String representation of the object.
*/
toString: function ()
{
return '[Phaser.Signal active:' + this.active + ' numListeners:' + this.getNumListeners() + ']';
}
};
/**
* Create a `dispatch` function that maintains a binding to the original Signal context.
*
* Use the resulting value if the dispatch function needs to be passed somewhere
* or called independently of the Signal object.
*
* @memberof Phaser.Signal
* @property {function} boundDispatch
*/
Object.defineProperty(Phaser.Signal.prototype, 'boundDispatch', {
get: function ()
{
var _this = this;
return this._boundDispatch || (this._boundDispatch = function ()
{
return _this.dispatch.apply(_this, arguments);
});
}
});
Phaser.Signal.prototype.constructor = Phaser.Signal;