atom/atom — pull request #2507 by benogle (2014-06-05 00:02:01+00:00)
Title: Add an API for decorations; render stuff in the gutter again

A decoration is an object attached to a buffer row. Here's a decoration:

```js
{type: 'gutter-class', class: 'no-wrap'}
```

And here is how to attach it to a buffer row:

```coffee
editor.addDecorationForBufferRow(1, {type: 'gutter-class', class: 'my-sweet-class'})
```

Currently the only thing that renders a decoration is the `GutterComponent` and it only cares about decorations with `type: 'gutter-class'`. It will add the decoration's `class` property as a class to the proper line-number node in the gutter.

The neat thing is that the `GutterComponent` handles all the bs with updating as line number nodes are added and removed. So no more watching the `display-updated` event and manually updating classes in packages like `git-diff` and `bookmarks`.

### Markers

There is a marker API as well. Packages like `bookmarks` should not be watching the markers and updating their decorations manually.

```coffee
marker = editor.displayBuffer.markBufferRange([[2, 13], [3, 15]], class: 'my-marker', invalidate: 'inside')
decoration = {type: 'gutter-class', class: 'marker-class'}
editor.addDecorationForMarker(marker, decoration)
```

The class `marker-class` will properly track the marker's rows on the gutter.

### Options

Sometimes you might want a decoration to show on wrapped lines (git-diff), and sometimes you dont (bookmarks), so there is an option: `softWrap`. Like so: `{type: 'gutter-class', class: 'marker-class', softWrap: true}`. If you have ideas on how better to pass options, let me know.

### Removing decorations

Currently you can only remove them on each buffer row. Like finding markers, it will remove any decoration that matches the pattern.

```coffee
editor.addDecorationForBufferRow(1, {type: 'gutter-class', class: 'my-sweet-class', namespace: 'cats'})
editor.addDecorationForBufferRow(1, {type: 'gutter-class', class: 'my-other-class', namespace: 'cats'})

# this will remove the previous two
editor.removeDecorationForBufferRow(1, {namespace: 'cats'})

# usually you'll probably just have one class and do this
editor.addDecorationForBufferRow(1, {type: 'gutter-class', class: 'my-other-class'})
```

The api works the same for marker decorations.

### TODO

* [ ] Deprecate the old gutter methods
* [ ] Figure out where to put this api. @nathansobo on the `ReactEditorView`?
* [ ] Maybe pull the folds out to be decorations??
* [ ] Docs

Fixes #1984