Phaser Class: Signal

## Phaser. Signal

#### new Signal()

  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.

  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.

  Source - core/Signal.js, line 60

### Members

#### active :boolean

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

  Default Value:
    - true
  Source - core/Signal.js, line 100

#### memorize :boolean

  Memorize the previously dispatched event?

  If an event has been memorized it is automatically dispatched when a new listener is added with add or addOnce.
  Use forget to clear any currently memorized event.

  Source - core/Signal.js, line 84

### Methods

#### add(listener, listenerContext, priority, args) → {Phaser.SignalBinding}

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

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `listener` | function |  |  | The function to call when this Signal is dispatched.
  `listenerContext` | object | <optional> |  | The context under which the listener will be executed (i.e. the object that should represent the `this` variable).
  `priority` | number | <optional> |  | 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)
  `args` | any | <optional> <repeatable> | (none) | Additional arguments to pass to the callback (listener) function. They will be appended after any arguments usually dispatched.

  ##### Returns:

  Phaser.SignalBinding -

  An Object representing the binding between the Signal and listener.

  Source - core/Signal.js, line 232

#### addOnce(listener, listenerContext, priority, args) → {Phaser.SignalBinding}

  Add a one-time listener - the listener is automatically removed after the first execution.

  If there is as memorized event then it will be dispatched and
  the listener will be removed immediately.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `listener` | function |  |  | The function to call when this Signal is dispatched.
  `listenerContext` | object | <optional> |  | The context under which the listener will be executed (i.e. the object that should represent the `this` variable).
  `priority` | number | <optional> |  | 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)
  `args` | any | <optional> <repeatable> | (none) | Additional arguments to pass to the callback (listener) function. They will be appended after any arguments usually dispatched.

  ##### Returns:

  Phaser.SignalBinding -

  An Object representing the binding between the Signal and listener.

  Source - core/Signal.js, line 274

#### dispatch(params)

  Dispatch / broadcast the event to all listeners.

  To create an instance-bound dispatch for this Signal, use boundDispatch.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `params` | any | <optional> | Parameters that should be passed to each handler.

  Source - core/Signal.js, line 395

#### dispose()

  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.

  Source - core/Signal.js, line 451

#### forget()

  Forget the currently memorized event, if any.

  Source - core/Signal.js, line 437

#### getNumListeners() → {integer}

  Gets the total number of listeners attached to this Signal.

  ##### Returns:

  integer -

  Number of listeners attached to the Signal.

  Source - core/Signal.js, line 369

#### halt()

  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 active to enable/disable the signal entirely.

  Source - core/Signal.js, line 381

#### has(listener, context) → {boolean}

  Check if a specific listener is attached.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `listener` | function |  | Signal handler function.
  `context` | object | <optional> | Context on which listener will be executed (object that should represent the `this` variable inside listener function).

  ##### Returns:

  boolean -

  If Signal has the specified listener.

  Source - core/Signal.js, line 218

#### remove(listener, context) → {function}

  Remove a single event listener.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `listener` | function |  |  | Handler function that should be removed.
  `context` | object | <optional> | null | Execution context (since you can add the same handler multiple times if executing in a different context).

  ##### Returns:

  function -

  Listener handler function.

  Source - core/Signal.js, line 305

#### removeAll(context)

  Remove all event listeners.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `context` | object | <optional> | null | If specified only listeners for the given context will be removed.

  Source - core/Signal.js, line 329

#### toString() → {string}

  A string representation of the object.

  ##### Returns:

  string -

  String representation of the object.

  Source - core/Signal.js, line 471