From 1b153f8d8d4b2f09afc2d039256c958e94bd3b05 Mon Sep 17 00:00:00 2001 From: Neil Date: Wed, 20 Dec 2023 09:24:23 +1100 Subject: Add IDocumentEditable interface for efficient interaction with document objects. --- doc/ScintillaDoc.html | 67 ++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 56 insertions(+), 11 deletions(-) (limited to 'doc/ScintillaDoc.html') diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index 27a542e90..3035d2210 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -129,7 +129,7 @@

Scintilla Documentation

-

Last edited 5 November 2023 NH

+

Last edited 19 December 2023 NH

Scintilla 5 has moved the lexers from Scintilla into a new Lexilla project.
@@ -402,34 +402,35 @@ ○ Multiple views ○ Background loading and saving - ○ Folding + ○ Document interface + ○ Folding ○ Line wrapping ○ Zooming - ○ Long lines + ○ Long lines ○ Accessibility ○ Lexer - ○ Lexer objects + ○ Lexer objects ○ Notifications ○ Images - ○ GTK + ○ GTK ○ Provisional messages ○ Deprecated messages - ○ Edit messages never supported by Scintilla + ○ Edit messages never supported by Scintilla ○ Removed features ○ Building Scintilla @@ -7203,9 +7204,11 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ windows (for use with splitter windows).

These messages use pointer returns and arguments to refer to documents. - They point to internal objects inside Scintilla and should be treated as an opaque void*. That - is, you can use and store the pointer as described in this section but you should not - dereference it.

+ They point to IDocumentEditable objects inside + Scintilla. + The IDocumentEditable interface is provisional and may change. + Client code can call IDocumentEditable methods. + Clients may just treat these as opaque void* values that are received from and passed to Scintilla without dereferencing.

SCI_GETDOCPOINTER → pointer
SCI_SETDOCPOINTER(<unused>, pointer doc)
SCI_CREATEDOCUMENT(position bytes, int documentOptions) → pointer
@@ -7339,7 +7342,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){

The documentOptions argument is described in the SCI_CREATEDOCUMENT section.

-

ILoader

+

ILoader

class ILoader {
@@ -7356,7 +7359,9 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ If a failure occurs in AddData or in a file reading call then loading can be abandoned and the loader released with the Release call. When the whole file has been read, ConvertToDocument should be called to produce a Scintilla - document pointer. The newly created document will have a reference count of 1 in the same way as a document pointer + document pointer. This pointer can be treated as a void* cookie to pass to other APIs or cast to a + IDocumentEditable* pointer. + The newly created document will have a reference count of 1 in the same way as a document pointer returned from SCI_CREATEDOCUMENT. There is no need to call Release after ConvertToDocument.

@@ -7373,6 +7378,46 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ The application may then decide to ignore the modification or to terminate the background saving thread and reenable modification before returning from the notification.

+

Document interface

+ +

Applications may want to manipulate documents that are not visible and the provisional IDocumentEditable + interface can be used for this.

+ +

IDocumentEditable allows more direct access to functionality and is faster than calling Scintilla APIs.

+ +

IDocumentEditable pointers are returned by + SCI_CREATEDOCUMENT, + SCI_GETDOCPOINTER, and + ILoader::ConvertToDocument.

+ +

They may be passed to + SCI_ADDREFDOCUMENT, + SCI_RELEASEDOCUMENT, and + SCI_SETDOCPOINTER, + .

+ +

IDocumentEditable

+ +
+class IDocumentEditable {
+public:
+        // Allow this interface to add methods over time and discover whether new methods available.
+        virtual int SCI_METHOD DEVersion() const noexcept = 0;
+
+        // Lifetime control
+        virtual int SCI_METHOD AddRef() noexcept = 0;
+        virtual int SCI_METHOD Release() = 0;
+};
+ +
+ +

The IDocumentEditable interface is being developed and more methods will be added in the future. + Its also possible that methods will change signatures or be removed. + Thus the feature is provisional and users should be aware that they may have to modify client code in response to these changes.

+ +

DEVersion will return 0 while IDocumentEditable is provisional and will return 1 + for the first stable release. After that, it will be incremented when new methods are added.

+

Folding

The fundamental operation in folding is making lines invisible or visible. Line visibility -- cgit v1.2.3