Implement API to read and write undo history from applications.

1 files changed, 103 insertions, 15 deletions

diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html
index 3035d2210..12f2be0eb 100644
--- a/doc/ScintillaDoc.html
+++ b/doc/ScintillaDoc.html
@@ -341,97 +341,101 @@
 
         <tr>
           <td>&cir; <a class="toc" href="#UndoAndRedo">Undo and Redo</a></td>
+          <td>&cir; <a class="toc" href="#UndoSaveRestore">Undo save and restore</a></td>
           <td>&cir; <a class="toc" href="#ChangeHistory">Change history</a></td>
-          <td>&cir; <a class="toc" href="#ScrollingAndAutomaticScrolling">Scrolling and automatic scrolling</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#ScrollingAndAutomaticScrolling">Scrolling and automatic scrolling</a></td>
           <td>&cir; <a class="toc" href="#WhiteSpace">White space</a></td>
           <td>&cir; <a class="toc" href="#Cursor">Cursor</a></td>
-          <td>&cir; <a class="toc" href="#MouseCapture">Mouse capture</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#MouseCapture">Mouse capture</a></td>
           <td>&cir; <a class="toc" href="#LineEndings">Line endings</a></td>
           <td>&cir; <a class="toc" href="#Words">Words</a></td>
-          <td>&cir; <a class="toc" href="#Styling">Styling</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#Styling">Styling</a></td>
           <td>&cir; <a class="toc" href="#StyleDefinition">Style definition</a></td>
           <td>&cir; <a class="toc" href="#ElementColours">Element colours</a></td>
-          <td>&cir; <a class="toc" href="#CaretAndSelectionStyles">Selection, caret, and hotspot styles</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#CaretAndSelectionStyles">Selection, caret, and hotspot styles</a></td>
           <td>&cir; <a class="toc" href="#CharacterRepresentations">Character representations</a></td>
           <td>&cir; <a class="toc" href="#Margins">Margins</a></td>
-          <td>&cir; <a class="toc" href="#Annotations">Annotations</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#Annotations">Annotations</a></td>
           <td>&cir; <a class="toc" href="#EndOfLineAnnotations">End of Line Annotations</a></td>
           <td>&cir; <a class="toc" href="#OtherSettings">Other settings</a></td>
-          <td>&cir; <a class="toc" href="#BraceHighlighting">Brace highlighting</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#BraceHighlighting">Brace highlighting</a></td>
           <td>&cir; <a class="toc" href="#TabsAndIndentationGuides">Tabs and Indentation Guides</a></td>
           <td>&cir; <a class="toc" href="#Markers">Markers</a></td>
-          <td>&cir; <a class="toc" href="#Indicators">Indicators</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#Indicators">Indicators</a></td>
           <td>&cir; <a class="toc" href="#Autocompletion">Autocompletion</a></td>
           <td>&cir; <a class="toc" href="#UserLists">User lists</a></td>
-          <td>&cir; <a class="toc" href="#CallTips">Call tips</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#CallTips">Call tips</a></td>
           <td>&cir; <a class="toc" href="#KeyboardCommands">Keyboard commands</a></td>
           <td>&cir; <a class="toc" href="#KeyBindings">Key bindings</a></td>
-          <td>&cir; <a class="toc" href="#PopupEditMenu">Popup edit menu</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#PopupEditMenu">Popup edit menu</a></td>
           <td>&cir; <a class="toc" href="#MacroRecording">Macro recording</a></td>
           <td>&cir; <a class="toc" href="#Printing">Printing</a></td>
-          <td>&cir; <a class="toc" href="#DirectAccess">Direct access</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#DirectAccess">Direct access</a></td>
           <td>&cir; <a class="toc" href="#MultipleViews">Multiple views</a></td>
           <td>&cir; <a class="toc" href="#BackgroundLoadSave">Background loading and saving</a></td>
-          <td>&cir; <a class="toc" href="#DocumentInterface">Document interface</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#DocumentInterface">Document interface</a></td>
           <td>&cir; <a class="toc" href="#Folding">Folding</a></td>
           <td>&cir; <a class="toc" href="#LineWrapping">Line wrapping</a></td>
-          <td>&cir; <a class="toc" href="#Zooming">Zooming</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#Zooming">Zooming</a></td>
           <td>&cir; <a class="toc" href="#LongLines">Long lines</a></td>
           <td>&cir; <a class="toc" href="#Accessibility">Accessibility</a></td>
-          <td>&cir; <a class="toc" href="#Lexer">Lexer</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#Lexer">Lexer</a></td>
           <td>&cir; <a class="toc" href="#LexerObjects">Lexer objects</a></td>
           <td>&cir; <a class="toc" href="#Notifications">Notifications</a></td>
-          <td>&cir; <a class="toc" href="#Images">Images</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#Images">Images</a></td>
           <td>&cir; <a class="toc" href="#GTK">GTK</a></td>
           <td>&cir; <a class="toc" href="#ProvisionalMessages"><span class="provisional">Provisional messages</span></a></td>
-          <td>&cir; <a class="toc" href="#DeprecatedMessages">Deprecated messages</a></td>
         </tr>
 
         <tr>
+          <td>&cir; <a class="toc" href="#DeprecatedMessages">Deprecated messages</a></td>
           <td>&cir; <a class="toc" href="#EditMessagesNeverSupportedByScintilla">Edit messages never supported by Scintilla</a></td>
           <td>&cir; <a class="toc" href="#RemovedFeatures">Removed features</a></td>
+        </tr>
+
+        <tr>
           <td>&cir; <a class="toc" href="#BuildingScintilla">Building Scintilla</a></td>
         </tr>
       </tbody>
@@ -1988,6 +1992,90 @@ struct Sci_TextToFindFull {
      look like typing or deletions that look like multiple uses of the Backspace or Delete keys.
      </p>
 
+    <h2 id="UndoSaveRestore">Undo Save and Restore</h2>
+
+    <p>This feature is unfinished and has limitations.
+    Restoring undo state is not compatible with change history so turn change history off before restoral.
+    The operation sequences discussed here are a 'golden path' that has been tested to some extent and calling
+    the APIs in other circumstances or with out-of-bounds values may cause failures.
+    The behaviour of tentative actions in save and restore is uncertain as these are meant to be short-term states in language input
+    and which need to synchronize with a language IME (input method editor).</p>
+
+    <p>It is possible to retrieve the undo stack from Scintilla and subsequently restore the state of the stack.</p>
+
+    <p>An application may save both the document and its save stack between sessions to enable the user to return
+    to the same state the next time they edit.
+    For this to work, the loaded file must be exactly the same as when the undo stack was saved.
+    If the file was changed, even in minor ways like converting line ends from Windows to Unix style then
+    the undo actions will not line up so undo may fail completely and will produce unexpected results.</p>
+
+    <code><a class="message" href="#SCI_GETUNDOACTIONS">SCI_GETUNDOACTIONS &rarr; int</a><br />
+     <a class="message" href="#SCI_SETUNDOSAVEPOINT">SCI_SETUNDOSAVEPOINT(int action)</a><br />
+     <a class="message" href="#SCI_GETUNDOSAVEPOINT">SCI_GETUNDOSAVEPOINT &rarr; int</a><br />
+     <a class="message" href="#SCI_SETUNDOCURRENT">SCI_SETUNDOCURRENT(int action)</a><br />
+     <a class="message" href="#SCI_GETUNDOCURRENT">SCI_GETUNDOCURRENT &rarr; int</a><br />
+     <a class="message" href="#SCI_SETUNDOTENTATIVE">SCI_SETUNDOTENTATIVE(int action)</a><br />
+     <a class="message" href="#SCI_GETUNDOTENTATIVE">SCI_GETUNDOTENTATIVE &rarr; int</a><br />
+     <a class="message" href="#SCI_PUSHUNDOACTIONTYPE">SCI_PUSHUNDOACTIONTYPE(int type, position pos)</a><br />
+     <a class="message" href="#SCI_CHANGELASTUNDOACTIONTEXT">SCI_CHANGELASTUNDOACTIONTEXT(position length, const char *text)</a><br />
+     <a class="message" href="#SCI_GETUNDOACTIONTYPE">SCI_GETUNDOACTIONTYPE(int action) &rarr; int</a><br />
+     <a class="message" href="#SCI_GETUNDOACTIONPOSITION">SCI_GETUNDOACTIONPOSITION(int action) &rarr; position</a><br />
+     <a class="message" href="#SCI_GETUNDOACTIONTEXT ">SCI_GETUNDOACTIONTEXT(int action, char *text) &rarr; int</a><br />
+    </code>
+
+    <h3 id="UndoSave">Save</h3>
+
+    <p>The retrieval APIs are the 'GET*' ones:
+    <code>SCI_GETUNDOACTIONS</code>,
+    <code>SCI_GETUNDOSAVEPOINT</code>,
+    <code>SCI_GETUNDOCURRENT</code>,
+    <code>SCI_GETUNDOTENTATIVE</code>,
+    <code>SCI_GETUNDOACTIONTYPE</code>,
+    <code>SCI_GETUNDOACTIONPOSITION</code>, and
+    <code>SCI_GETUNDOACTIONTEXT</code>.
+    </p>
+
+    <p>The <code>SCI_GETUNDOACTIONS</code>,
+    <code>SCI_GETUNDOSAVEPOINT</code>, <code>SCI_GETUNDOCURRENT</code>, and
+    <code>SCI_GETUNDOTENTATIVE</code> APIs each return a single value and may be called in any order.
+    </p>
+
+    <p>The <code>SCI_GETUNDOACTIONTYPE</code>,
+    <code>SCI_GETUNDOACTIONPOSITION</code>, and <code>SCI_GETUNDOACTIONTEXT</code>
+    APIs take an action index and should be called with indices from 0 to one less than the result of
+    <code>SCI_GETUNDOACTIONS</code>.
+    The actions should only be iterated in the positive direction and should start from 0.
+    That is because undo stack data is not all randomly accessible and iterating in other orders may take O(n^2) time.
+    Data may also be inaccurate if a cursor is not initialised first with 0 index calls.
+    </p>
+
+    <h3 id="UndoRestore">Restore</h3>
+
+    <p>Restoration is only possible when the undo state is empty so <code>SCI_EMPTYUNDOBUFFER</code>
+    should be called first if there may already be some undo actions.</p>
+
+    <p>The restore APIs are the 'SET*' and others:
+    <code>SCI_SETUNDOSAVEPOINT</code>,
+    <code>SCI_SETUNDOCURRENT</code>,
+    <code>SCI_SETUNDOTENTATIVE</code>,
+    <code>SCI_PUSHUNDOACTIONTYPE</code>, and
+    <code>SCI_CHANGELASTUNDOACTIONTEXT</code>.
+    </p>
+
+    <p>The history should first be set up with <code>SCI_PUSHUNDOACTIONTYPE</code>, and
+    <code>SCI_CHANGELASTUNDOACTIONTEXT</code> then the save, current, and tentativ points set
+    with <code>SCI_SETUNDOSAVEPOINT</code>, <code>SCI_SETUNDOCURRENT</code>, and
+    <code>SCI_SETUNDOTENTATIVE</code>.
+    </p>
+
+    <p><code>SCI_PUSHUNDOACTIONTYPE(int type, position pos)</code> appends an action to the undo stack
+    with a particular type and position then the text and length of that action are set with
+    <code>SCI_CHANGELASTUNDOACTIONTEXT(position length, const char *text)</code>.
+    </p>
+
+    <p>The current implementation may only work when the current and save point are the same and there is no tentative point.
+    </p>
+
     <h2 id="ChangeHistory">Change history</h2>
 
     <p>Scintilla can display document changes (modified, saved, ...) in the margin or in the text.</p>