Add IDocumentEditable interface for efficient interaction with document objects.

2 files changed, 63 insertions, 11 deletions

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 @@
 
     <h1>Scintilla Documentation</h1>
 
-    <p>Last edited 5 November 2023 NH</p>
+    <p>Last edited 19 December 2023 NH</p>
 
     <p style="background:#90F0C0">Scintilla 5 has moved the lexers from Scintilla into a new
     <a href="Lexilla.html">Lexilla</a> project.<br />
@@ -402,34 +402,35 @@
         <tr>
           <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="#Folding">Folding</a></td>
+          <td>&cir; <a class="toc" href="#DocumentInterface">Document interface</a></td>
         </tr>
 
         <tr>
+          <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>
-          <td>&cir; <a class="toc" href="#LongLines">Long lines</a></td>
         </tr>
 
         <tr>
+          <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>
-          <td>&cir; <a class="toc" href="#LexerObjects">Lexer objects</a></td>
         </tr>
 
         <tr>
+          <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>
-          <td>&cir; <a class="toc" href="#GTK">GTK</a></td>
         </tr>
 
         <tr>
+          <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>
-          <td>&cir; <a class="toc" href="#EditMessagesNeverSupportedByScintilla">Edit messages never supported by Scintilla</a></td>
         </tr>
 
         <tr>
+          <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>
           <td>&cir; <a class="toc" href="#BuildingScintilla">Building Scintilla</a></td>
         </tr>
@@ -7203,9 +7204,11 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
     windows (for use with splitter windows).</p>
 
     <p>These messages use <code>pointer</code> returns and arguments to refer to documents.
-    They point to internal objects inside Scintilla and should be treated as an opaque <code>void*</code>. That
-    is, you can use and store the pointer as described in this section but you should not
-    dereference it.</p>
+    They point to <a class="seealso" href="#IDocumentEditable" style="background:#FFB000">IDocumentEditable</a> objects inside
+    Scintilla.
+    The <code>IDocumentEditable</code> interface is provisional and may change.
+    Client code can call <code>IDocumentEditable</code> methods.
+    Clients may just treat these as opaque <code>void*</code> values that are received from and passed to Scintilla without dereferencing.</p>
     <code><a class="message" href="#SCI_GETDOCPOINTER">SCI_GETDOCPOINTER &rarr; pointer</a><br />
      <a class="message" href="#SCI_SETDOCPOINTER">SCI_SETDOCPOINTER(&lt;unused&gt;, pointer doc)</a><br />
      <a class="message" href="#SCI_CREATEDOCUMENT">SCI_CREATEDOCUMENT(position bytes, int documentOptions) &rarr; pointer</a><br />
@@ -7339,7 +7342,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
     <p>The <code class="parameter">documentOptions</code> argument
     is described in the <a class="seealso" href="#documentOptions"><code>SCI_CREATEDOCUMENT</code></a> section.</p>
 
-<h4>ILoader</h4>
+<h4 id="ILoader">ILoader</h4>
 
 <div class="highlighted">
 <span class="S5">class</span><span class="S0"> </span>ILoader<span class="S0"> </span><span class="S10">{</span><br />
@@ -7356,7 +7359,9 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
     If a failure occurs in <code>AddData</code> or in a file reading call then loading can be abandoned and the loader released with
     the <code>Release</code> call.
     When the whole file has been read, <code>ConvertToDocument</code> 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 <code>void*</code> cookie to pass to other APIs or cast to a
+    <a class="seealso" href="#IDocumentEditable" style="background:#FFB000">IDocumentEditable*</a> pointer.
+    The newly created document will have a reference count of 1 in the same way as a document pointer
     returned from
     <a class="seealso" href="#SCI_CREATEDOCUMENT">SCI_CREATEDOCUMENT</a>.
     There is no need to call <code>Release</code> after <code>ConvertToDocument</code>.</p>
@@ -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.</p>
 
+   <h2 id="DocumentInterface" class="provisional">Document interface</h2>
+
+    <p>Applications may want to manipulate documents that are not visible and the provisional <code>IDocumentEditable</code>
+    interface can be used for this.</p>
+
+    <p><code>IDocumentEditable</code> allows more direct access to functionality and is faster than calling Scintilla APIs.</p>
+
+    <p><code>IDocumentEditable</code> pointers are returned by
+    <a class="seealso" href="#SCI_CREATEDOCUMENT">SCI_CREATEDOCUMENT</a>,
+    <a class="seealso" href="#SCI_GETDOCPOINTER">SCI_GETDOCPOINTER</a>, and
+    <a class="seealso" href="#ILoader">ILoader::ConvertToDocument</a>.</p>
+
+    <p>They may be passed to
+    <a class="seealso" href="#SCI_ADDREFDOCUMENT">SCI_ADDREFDOCUMENT</a>,
+    <a class="seealso" href="#SCI_RELEASEDOCUMENT">SCI_RELEASEDOCUMENT</a>, and
+    <a class="seealso" href="#SCI_SETDOCPOINTER">SCI_SETDOCPOINTER</a>,
+    .</p>
+
+<h4 id="IDocumentEditable">IDocumentEditable</h4>
+
+<div class="highlighted" style="background:#FFD270;border: 1px solid #FFBB00">
+<span><span class="S5">class</span><span class="S0"> </span>IDocumentEditable<span class="S0"> </span><span class="S10">{</span><br />
+<span class="S5">public</span><span class="S10">:</span><br />
+<span class="S0">&nbsp; &nbsp; &nbsp; &nbsp; </span><span class="S2">// Allow this interface to add methods over time and discover whether new methods available.</span><br />
+<span class="S0">&nbsp; &nbsp; &nbsp; &nbsp; </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>DEVersion<span class="S10">()</span><span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S5">noexcept</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
+<br />
+<span class="S0">&nbsp; &nbsp; &nbsp; &nbsp; </span><span class="S2">// Lifetime control</span><br />
+<span class="S0">&nbsp; &nbsp; &nbsp; &nbsp; </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>AddRef<span class="S10">()</span><span class="S0"> </span><span class="S5">noexcept</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
+<span class="S0">&nbsp; &nbsp; &nbsp; &nbsp; </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>Release<span class="S10">()</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
+<span class="S10">};</span><br />
+<span class="S0"></span></span>
+</div>
+
+    <p>The <code>IDocumentEditable</code> 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.</p>
+
+    <p><code>DEVersion</code> will return 0 while <code>IDocumentEditable</code> is provisional and will return 1
+    for the first stable release. After that, it will be incremented when new methods are added.</p>
+
     <h2 id="Folding">Folding</h2>
 
     <p>The fundamental operation in folding is making lines invisible or visible. Line visibility
diff --git a/doc/ScintillaHistory.html b/doc/ScintillaHistory.html
index 00023b102..a3d44d4ae 100644
--- a/doc/ScintillaHistory.html
+++ b/doc/ScintillaHistory.html
@@ -591,6 +591,13 @@
 	Released 18 November 2023.
 	</li>
 	<li>
+	Add IDocumentEditable interface to allow efficient interaction with document objects which may not be visible in
+	a Scintilla instance. This feature is provisonal and may change before being declared stable.
+	For better type-safety, the ScintillaCall C++ API uses IDocumentEditable* where void* was used before which may require
+	changes to client code that uses document pointer APIs
+	DocPointer, SetDocPointer, CreateDocument, AddRefDocument, and ReleaseDocument.
+	</li>
+	<li>
 	Ctrl-click on a selection deselects it in multiple selection mode.
 	</li>
 	<li>