diff options
| -rw-r--r-- | doc/ScintillaDoc.html | 71 |
1 files changed, 64 insertions, 7 deletions
diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index 913316228..c68fcc0fd 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -291,37 +291,41 @@ </tr> <tr> + <td>o <a class="toc" href="#BackgroundLoadSave">Background loading and saving</a></td> + <td>o <a class="toc" href="#Folding">Folding</a></td> <td>o <a class="toc" href="#LineWrapping">Line wrapping</a></td> - - <td>o <a class="toc" href="#Zooming">Zooming</a></td> </tr> <tr> + <td>o <a class="toc" href="#Zooming">Zooming</a></td> + <td>o <a class="toc" href="#LongLines">Long lines</a></td> <td>o <a class="toc" href="#Lexer">Lexer</a></td> - - <td>o <a class="toc" href="#LexerObjects">Lexer objects</a></td> </tr> <tr> + <td>o <a class="toc" href="#LexerObjects">Lexer objects</a></td> + <td>o <a class="toc" href="#Notifications">Notifications</a></td> <td>o <a class="toc" href="#Images">Images</a></td> - - <td>o <a class="toc" href="#GTK">GTK+</a></td> </tr> <tr> + <td>o <a class="toc" href="#GTK">GTK+</a></td> + <td>o <a class="toc" href="#DeprecatedMessages">Deprecated messages</a></td> <td>o <a class="toc" href="#EditMessagesNeverSupportedByScintilla">Edit messages never supported by Scintilla</a></td> - <td>o <a class="toc" href="#BuildingScintilla">Building Scintilla</a></td> + </tr> + <tr> + <td>o <a class="toc" href="#BuildingScintilla">Building Scintilla</a></td> </tr> </tbody> </table> @@ -4840,6 +4844,59 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ world spinning in its orbit you must balance each call to <code>SCI_CREATEDOCUMENT</code> or <code>SCI_ADDREFDOCUMENT</code> with a call to <code>SCI_RELEASEDOCUMENT</code>.</p> + <h2 id="BackgroundLoadSave">Background loading and saving</h2> + + <p>To ensure a responsive user interface, applications may decide to load and save documents using a separate thread + from the user interface.</p> + + <h3 id="BackgroundLoad">Loading in the background</h2> + + <p>An application can load all of a file into a buffer it allocates on a background thread and then add the data in that buffer + into a Scintilla document on the user interface thread. That technique uses extra memory to store a complete copy of the + file and also means that the time that Scintilla takes to perform initial line end discovery blocks the user interface.</p> + + <p>To avoid these issues, a loader object may be created and used to load the file. The loader object supports the ILoader interface.</p> + + <p><b id="SCI_CREATELOADER">SCI_CREATELOADER(int bytes)</b><br /> + Create an object that supports the <code>ILoader</code> interface which can be used to load data and then + be turned into a Scintilla document object for attachment to a view object. + The <code>bytes</code> argument determines the initial memory allocation for the document as it is more efficient + to allocate once rather than rely on the buffer growing as data is added. + If <code>SCI_CREATELOADER</code> fails then 0 is returned.</p> + +<h4>ILoader</h4> + +<div class="highlighted"> +<span class="S5">class</span><span class="S0"> </span>ILoader<span class="S0"> </span><span class="S10">{</span><br /> +<span class="S5">public</span><span class="S10">:</span><br /> +<span class="S0"> </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="S0"> </span><span class="S2">// Returns a status code from SC_STATUS_*</span><br /> +<span class="S0"> </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>AddData<span class="S10">(</span><span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>data<span class="S10">,</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>length<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="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">void</span><span class="S0"> </span><span class="S10">*</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>ConvertToDocument<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 /> +</div> + + <p>The application should call the <code>AddData</code> method with each block of data read from the file. + <code>AddData</code> will return SC_STATUS_OK unless a failure, such as memory exhaustion occurs. + 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, the <code>ConvertToDocument</code> method should be called to produce a Scintilla + document pointer which can be used in the same way as a document pointer returned from + <a class="message" href="#SCI_CREATEDOCUMENT">SCI_CREATEDOCUMENT</a>. + There is no need to call <code>Release</code> after <code>ConvertToDocument</code>.</p> + + <h3 id="BackgroundSave">Saving in the background</h2> + + <p>An application that wants to save in the background should lock the document with <code>SCI_SETREADONLY(1)</code> + to prevent modifications and retrieve a pointer to the unified document contents with + <a class="message" href="#SCI_GETCHARACTERPOINTER">SCI_GETCHARACTERPOINTER</a></code>. + The buffer of a locked document will not move so the pointer is valid until the application calls <code>SCI_SETREADONLY(0)</code>.</p> + + <p>If the user tries to performs a modification while the document is locked then a <code><a class="message" + href="#SCN_MODIFYATTEMPTRO">SCN_MODIFYATTEMPTRO</a></code> notification is sent to the application. + 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="Folding">Folding</h2> <p>The fundamental operation in folding is making lines invisible or visible. Line visibility |