[Gutter] Create event subscription methods for gutter changes

spec/text-editor-spec.coffee

@@ -4296,3 +4296,77 @@ describe "TextEditor", ->
         class: 'test-class'
       expect(gutterDecorations.length).toBe 1
       expect(gutterDecorations[0]).toBe decoration
+
+  describe '::observeGutters', ->
+    [payloads, callback] = []
+
+    beforeEach ->
+      payloads = []
+      callback = (payload) ->
+        payloads.push(payload)
+
+    it 'calls the callback immediately with each existing gutter, and with each added gutter after that.', ->
+      lineNumberGutter = editor.gutterWithName('line-number')
+      editor.observeGutters(callback)
+      expect(payloads).toEqual [lineNumberGutter]
+      gutter1 = editor.addGutter({name: 'test-gutter-1'})
+      expect(payloads).toEqual [lineNumberGutter, gutter1]
+      gutter2 = editor.addGutter({name: 'test-gutter-2'})
+      expect(payloads).toEqual [lineNumberGutter, gutter1, gutter2]
+
+    it 'does not call the callback when a gutter is removed.', ->
+      gutter = editor.addGutter({name: 'test-gutter'})
+      editor.observeGutters(callback)
+      payloads = []
+      gutter.destroy()
+      expect(payloads).toEqual []
+
+    it 'does not call the callback after the subscription has been disposed.', ->
+      subscription = editor.observeGutters(callback)
+      payloads = []
+      subscription.dispose()
+      editor.addGutter({name: 'test-gutter'})
+      expect(payloads).toEqual []
+
+  describe '::onDidAddGutter', ->
+    [payloads, callback] = []
+
+    beforeEach ->
+      payloads = []
+      callback = (payload) ->
+        payloads.push(payload)
+
+    it 'calls the callback with each newly-added gutter, but not with existing gutters.', ->
+      editor.onDidAddGutter(callback)
+      expect(payloads).toEqual []
+      gutter = editor.addGutter({name: 'test-gutter'})
+      expect(payloads).toEqual [gutter]
+
+    it 'does not call the callback after the subscription has been disposed.', ->
+      subscription = editor.onDidAddGutter(callback)
+      payloads = []
+      subscription.dispose()
+      editor.addGutter({name: 'test-gutter'})
+      expect(payloads).toEqual []
+
+  describe '::onDidRemoveGutter', ->
+    [payloads, callback] = []
+
+    beforeEach ->
+      payloads = []
+      callback = (payload) ->
+        payloads.push(payload)
+
+    it 'calls the callback when a gutter is removed.', ->
+      gutter = editor.addGutter({name: 'test-gutter'})
+      editor.onDidRemoveGutter(callback)
+      expect(payloads).toEqual []
+      gutter.destroy()
+      expect(payloads).toEqual ['test-gutter']
+
+    it 'does not call the callback after the subscription has been disposed.', ->
+      gutter = editor.addGutter({name: 'test-gutter'})
+      subscription = editor.onDidRemoveGutter(callback)
+      subscription.dispose()
+      gutter.destroy()
+      expect(payloads).toEqual []

src/gutter-container.coffee

@@ -46,6 +46,7 @@ class GutterContainer
         break
     if !inserted
       @gutters.push newGutter
+    @emitter.emit 'did-add-gutter', newGutter
     return newGutter
 
   getGutters: ->
@@ -60,7 +61,16 @@ class GutterContainer
   Section: Event Subscription
   ###
 
-  # @param callback: function( nameOfRemovedGutter )
+  # See {TextEditor::observeGutters} for details.
+  observeGutters: (callback) ->
+    callback(gutter) for gutter in @getGutters()
+    @onDidAddGutter callback
+
+  # See {TextEditor::onDidAddGutter} for details.
+  onDidAddGutter: (callback) ->
+    @emitter.on 'did-add-gutter', callback
+
+  # See {TextEditor::onDidRemoveGutter} for details.
   onDidRemoveGutter: (callback) ->
     @emitter.on 'did-remove-gutter', callback
 

src/text-editor.coffee

@@ -524,6 +524,34 @@ class TextEditor extends Model
   gutterWithName: (name) ->
     @gutterContainer.gutterWithName name
 
+  # Calls your `callback` when a {Gutter} is added to the editor.
+  # Immediately calls your callback for each existing gutter.
+  #
+  # * `callback` {Function}
+  #   * `gutter` {Gutter} that currently exists/was added.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
+  observeGutters: (callback) ->
+    @gutterContainer.observeGutters callback
+
+  # Calls your `callback` when a {Gutter} is added to the editor.
+  #
+  # * `callback` {Function}
+  #   * `gutter` {Gutter} that was added.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
+  onDidAddGutter: (callback) ->
+    @gutterContainer.onDidAddGutter callback
+
+  # Calls your `callback` when a {Gutter} is removed from the editor.
+  #
+  # * `callback` {Function}
+  #   * `name` The name of the {Gutter} that was removed.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
+  onDidRemoveGutter: (callback) ->
+    @gutterContainer.onDidRemoveGutter callback
+
   # Set the number of characters that can be displayed horizontally in the
   # editor.
   #