From bd53ffcbefe4e7a22fc493b1916939bae5f9dc1d Mon Sep 17 00:00:00 2001 From: Neil Date: Fri, 9 Feb 2024 21:45:35 +1100 Subject: Implement API to read and write undo history from applications. --- doc/ScintillaDoc.html | 118 +++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 103 insertions(+), 15 deletions(-) (limited to 'doc/ScintillaDoc.html') 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 @@ ○ Undo and Redo + ○ Undo save and restore ○ Change history - ○ Scrolling and automatic scrolling + ○ Scrolling and automatic scrolling ○ White space ○ Cursor - ○ Mouse capture + ○ Mouse capture ○ Line endings ○ Words - ○ Styling + ○ Styling ○ Style definition ○ Element colours - ○ Selection, caret, and hotspot styles + ○ Selection, caret, and hotspot styles ○ Character representations ○ Margins - ○ Annotations + ○ Annotations ○ End of Line Annotations ○ Other settings - ○ Brace highlighting + ○ Brace highlighting ○ Tabs and Indentation Guides ○ Markers - ○ Indicators + ○ Indicators ○ Autocompletion ○ User lists - ○ Call tips + ○ Call tips ○ Keyboard commands ○ Key bindings - ○ Popup edit menu + ○ Popup edit menu ○ Macro recording ○ Printing - ○ Direct access + ○ Direct access ○ Multiple views ○ Background loading and saving - ○ Document interface + ○ Document interface ○ Folding ○ Line wrapping - ○ Zooming + ○ Zooming ○ Long lines ○ Accessibility - ○ Lexer + ○ Lexer ○ Lexer objects ○ Notifications - ○ Images + ○ Images ○ GTK ○ Provisional messages - ○ Deprecated messages + ○ Deprecated messages ○ Edit messages never supported by Scintilla ○ Removed features + + + ○ Building Scintilla @@ -1988,6 +1992,90 @@ struct Sci_TextToFindFull { look like typing or deletions that look like multiple uses of the Backspace or Delete keys.

+

Undo Save and Restore

+ +

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).

+ +

It is possible to retrieve the undo stack from Scintilla and subsequently restore the state of the stack.

+ +

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.

+ + SCI_GETUNDOACTIONS → int
+ SCI_SETUNDOSAVEPOINT(int action)
+ SCI_GETUNDOSAVEPOINT → int
+ SCI_SETUNDOCURRENT(int action)
+ SCI_GETUNDOCURRENT → int
+ SCI_SETUNDOTENTATIVE(int action)
+ SCI_GETUNDOTENTATIVE → int
+ SCI_PUSHUNDOACTIONTYPE(int type, position pos)
+ SCI_CHANGELASTUNDOACTIONTEXT(position length, const char *text)
+ SCI_GETUNDOACTIONTYPE(int action) → int
+ SCI_GETUNDOACTIONPOSITION(int action) → position
+ SCI_GETUNDOACTIONTEXT(int action, char *text) → int
+ + +

Save

+ +

The retrieval APIs are the 'GET*' ones: + SCI_GETUNDOACTIONS, + SCI_GETUNDOSAVEPOINT, + SCI_GETUNDOCURRENT, + SCI_GETUNDOTENTATIVE, + SCI_GETUNDOACTIONTYPE, + SCI_GETUNDOACTIONPOSITION, and + SCI_GETUNDOACTIONTEXT. +

+ +

The SCI_GETUNDOACTIONS, + SCI_GETUNDOSAVEPOINT, SCI_GETUNDOCURRENT, and + SCI_GETUNDOTENTATIVE APIs each return a single value and may be called in any order. +

+ +

The SCI_GETUNDOACTIONTYPE, + SCI_GETUNDOACTIONPOSITION, and SCI_GETUNDOACTIONTEXT + APIs take an action index and should be called with indices from 0 to one less than the result of + SCI_GETUNDOACTIONS. + 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. +

+ +

Restore

+ +

Restoration is only possible when the undo state is empty so SCI_EMPTYUNDOBUFFER + should be called first if there may already be some undo actions.

+ +

The restore APIs are the 'SET*' and others: + SCI_SETUNDOSAVEPOINT, + SCI_SETUNDOCURRENT, + SCI_SETUNDOTENTATIVE, + SCI_PUSHUNDOACTIONTYPE, and + SCI_CHANGELASTUNDOACTIONTEXT. +

+ +

The history should first be set up with SCI_PUSHUNDOACTIONTYPE, and + SCI_CHANGELASTUNDOACTIONTEXT then the save, current, and tentativ points set + with SCI_SETUNDOSAVEPOINT, SCI_SETUNDOCURRENT, and + SCI_SETUNDOTENTATIVE. +

+ +

SCI_PUSHUNDOACTIONTYPE(int type, position pos) appends an action to the undo stack + with a particular type and position then the text and length of that action are set with + SCI_CHANGELASTUNDOACTIONTEXT(position length, const char *text). +

+ +

The current implementation may only work when the current and save point are the same and there is no tentative point. +

+

Change history

Scintilla can display document changes (modified, saved, ...) in the margin or in the text.

-- cgit v1.2.3