Emitter Essential

Utility class to be used when implementing event-based APIs that allows for handlers registered via ::on to be invoked with calls to ::emit. Instances of this class are intended to be used internally by classes that expose an event-based API.

For example:

class User {
  constructor() {
    this.emitter = new Emitter()
  }

  onDidChangeName(callback) {
    this.emitter.on('did-change-name', callback)
  }

  setName(name) {
    if (name !== this.name) {
      this.name = name
      this.emitter.emit('did-change-name', name)
    }

    return this.name
  }
}

Construction and Destruction

::constructor()

Construct an emitter.

this.emitter = new Emitter()

::clear()

Clear out any existing subscribers.

::dispose()

Unsubscribe all handlers.

Event Subscription

::on(eventName, handler)

Argument	Description
`eventName`	String naming the event that you want to invoke the handler when emitted.
`handler`	Function to invoke when ::emit is called with the given event name.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::once(eventName, handler)

Argument	Description
`eventName`	String naming the event that you want to invoke the handler when emitted.
`handler`	Function to invoke when ::emit is called with the given event name.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::preempt(eventName, handler)

Register the given handler function to be invoked before all other handlers existing at the time of subscription whenever events by the given name are emitted via ::emit.

Use this method when you need to be the first to handle a given event. This could be required when a data structure in a parent object needs to be updated before third-party event handlers registered on a child object via a public API are invoked. Your handler could itself be preempted via subsequent calls to this method, but this can be controlled by keeping methods based on ::preempt private.

Argument	Description
`eventName`	String naming the event that you want to invoke the handler when emitted.
`handler`	Function to invoke when ::emit is called with the given event name.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

Event Emission

::emit(eventName, value)

Invoke handlers registered via ::on for the given event name.

Argument	Description
`eventName`	The name of the event to emit. Handlers registered with ::on for the same name will be invoked.
`value`	Callbacks will be invoked with this value as an argument.

Chapter 1: Getting Started

Chapter 2: Using Atom

Chapter 3: Hacking Atom

Chapter 4: Behind Atom

Reference: API

Appendix A: Resources

Appendix B: FAQ

Appendix C: Shadow DOM

Appendix D: Upgrading to 1.0 APIs

Appendix E: Atom server-side APIs

mac

windows

linux