From f39367fc4c7af72caef8e20b1e9b1a038e242b0a Mon Sep 17 00:00:00 2001 From: Neil Date: Fri, 16 Feb 2024 09:52:43 +1100 Subject: Implement detach point access with SCI_SETUNDODETACH and SCI_GETUNDODETACH. Write more documentation for undo history. --- doc/ScintillaDoc.html | 47 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 32 insertions(+), 15 deletions(-) (limited to 'doc/ScintillaDoc.html') diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index 4a10d280f..b866cf291 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -129,7 +129,7 @@

Scintilla Documentation

-

Last edited 19 December 2023 NH

+

Last edited 16 February 2024 NH

Scintilla 5 has moved the lexers from Scintilla into a new Lexilla project.
@@ -1995,11 +1995,23 @@ struct Sci_TextToFindFull {

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. + Restoring change history alongside undo state is unfinished 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).

+ 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). + For now, restore the tentative point to -1 as it seems safest to regard the tentative change as committed.

+ +

Scintilla stores each change in an undo stack. + Various inter-action points play roles in undo behaviour: actions count, save point, detach point, + tentative point, and current action. Just like positions in documents, these points are between actions in the + undo stack. Thus the current action specifies the number of actions that led to the current document state and + actions after this are for redo. + The save point specifies that the actions before this point are in the most recent save and actions after this are not yet saved.

+

When the user undoes from a save point and then performs a new change, the save point can no longer be reached and is -1. + The detach point is the point at which the undo stack branched away from the saved state and is used by + change history.

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

@@ -2012,10 +2024,12 @@ struct Sci_TextToFindFull { SCI_GETUNDOACTIONS → int
SCI_SETUNDOSAVEPOINT(int action)
SCI_GETUNDOSAVEPOINT → int
- SCI_SETUNDOCURRENT(int action)
- SCI_GETUNDOCURRENT → int
+ SCI_SETUNDODETACH(int action)
+ SCI_GETUNDODETACH → int
SCI_SETUNDOTENTATIVE(int action)
SCI_GETUNDOTENTATIVE → int
+ SCI_SETUNDOCURRENT(int action)
+ SCI_GETUNDOCURRENT → int
SCI_PUSHUNDOACTIONTYPE(int type, position pos)
SCI_CHANGELASTUNDOACTIONTEXT(position length, const char *text)
SCI_GETUNDOACTIONTYPE(int action) → int
@@ -2028,16 +2042,18 @@ struct Sci_TextToFindFull {

The retrieval APIs are the 'GET*' ones: SCI_GETUNDOACTIONS, SCI_GETUNDOSAVEPOINT, - SCI_GETUNDOCURRENT, + SCI_GETUNDODETACH, SCI_GETUNDOTENTATIVE, + SCI_GETUNDOCURRENT, 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. + SCI_GETUNDOSAVEPOINT, SCI_GETUNDODETACH, + SCI_GETUNDOTENTATIVE, and SCI_GETUNDOCURRENT + APIs each return a single value and may be called in any order.

The SCI_GETUNDOACTIONTYPE, @@ -2056,15 +2072,16 @@ struct Sci_TextToFindFull {

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

-

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

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

@@ -2076,7 +2093,7 @@ struct Sci_TextToFindFull {

The last restoration API called should be SCI_SETUNDOCURRENT as this validates the restored history and values against the document. For example, an undo history that could cause a negative - document length or inserting / removing text outside the document is invalid. + document length or insert / remove text outside the document is invalid. If the restored undo state is invalid then a failure status is set and the undo history cleared. Check for failure with SCI_GETSTATUS.

-- cgit v1.2.3