Decorations
July 24, 2014 benogle
One very common pattern we’ve seen in packages is highlighting bits of the editor. A package might add an icon to line numbers, colorize lines, or draw a rectangle around a word.
Other than the gutter, there was no API for highlighting things. There are markers, but markers offered no visual representation. So each package had to implement its own version of marker views and line highlighting. Implementing these things is redundant and error prone. Some package authors may have even avoided writing neat features because they needed to do this work.
With the Decoration API available in the React editor, you no longer need to re-implement these things. It’s as simple as this:
range = editor.getSelectedBufferRange() # or any range you like
marker = editor.markBufferRange(range)
decoration = editor.decorateMarker(marker, {type: 'line', class: 'my-line-class'})
Decorations are based on markers. Markers allow you to mark a range in an editor and follow the marked text around as changes are made to the buffer. eg. Add a marker on line 10, and a newline on line 1. Your marker will now point to line 11. A decoration is the visual representation of a marker.
Pulling decorations into Atom core gives us another advantage: performance. By controlling the decoration rendering, we can make sure they are fast. And each performance enhancement we make to decorations will speed up big chunks of the entire editor: selections, folds, find and replace, and even your packages.
In use today
Now that the React editor is enabled by default, selections, fold markers, and cursor line indicators are all decorations.
Several of the built in packages use decorations as well: git-diff (for gutter diff indicators), bookmarks (for gutter book mark indicators), and find-and-replace (for boxes around found search terms).
Resources
Check out Editor::decorateMarker, the Decoration API docs, TextBuffer::markRange and the Marker docs.
We’ve made a decoration-example package demonstrating the capabilities of the Decoration API.
Update your packages
Decorations are the future. Decorations will only be rendered when the new React editor is enabled, which is the default. The API is available no matter which editor is use, so you can start using Decorations right away. This duality will be going away very shortly — the old editor will be removed entirely within the next couple weeks.
We’re excited to see what you come up with!