marijnh/CodeMirror — pull request #919 by njx (2012-10-30 23:02:54+00:00)
Title: Add "dirty state" tracking to history mechanism

The intent of this new API is to make it possible to track the "dirty state" of a document, corresponding to the "dirty dot" functionality common in document editors. The dirty state reflects whether the user has undone/redone to the point where they last saved the document, corresponding (in this API) to the last time the `markClean()` function was called.

The heuristics are mostly straightforward, but there are a couple of edge cases that are worth calling out.

1. If the document is clean, the user makes changes, and then the user undoes those changes, the document is clean again.
2. If the user undoes past the last clean state, the document is dirty. If the user then redoes back to the clean state, the document is clean.
3. If the user undoes past the last clean state, and then makes changes without redoing, then the document can never become clean again until the next time `markClean()` is explicitly called (because there's no way to redo back to the clean state, since the redo history will be cleared).

We implemented this functionality back in our fork of v2, before the `getHistory()` API was available. I couldn't think of a straightforward way to implement this externally to CodeMirror even with that API, because it's hard for us to know exactly what kind of edit happened. It seems simpler to do it in CodeMirror, and I think the functionality would generally be useful for people implementing editors.