From 255d2d33abf4c2c5a918bacde049004e52b7986f Mon Sep 17 00:00:00 2001 From: Neil Date: Tue, 17 Apr 2018 08:23:18 +1000 Subject: Add SC_DOCUMENTOPTION_TEXT_LARGE option for documents larger than 2 GigaBytes. This option is provisional and experimental. --- doc/ScintillaDoc.html | 49 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 38 insertions(+), 11 deletions(-) (limited to 'doc/ScintillaDoc.html') diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index 25e7ca15b..d9f658814 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -119,7 +119,7 @@

Scintilla Documentation

-

Last edited 1 February 2018 NH

+

Last edited 17 April 2018 NH

There is an overview of the internal design of Scintilla.
@@ -5711,11 +5711,12 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ SCI_GETDOCPOINTER → document *
SCI_SETDOCPOINTER(<unused>, document *doc)
- SCI_CREATEDOCUMENT(int bytes, int documentOption) → document *
+ SCI_CREATEDOCUMENT(int bytes, int documentOptions) → document *
SCI_ADDREFDOCUMENT(<unused>, document *doc)
SCI_RELEASEDOCUMENT(<unused>, document *doc)
+ SCI_GETDOCUMENTOPTIONS → int

SCI_GETDOCPOINTER → document *
@@ -5732,7 +5733,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ window.
6. If doc was not 0, its reference count is increased by 1.

-

SCI_CREATEDOCUMENT(int bytes, int documentOption) → document *
+

SCI_CREATEDOCUMENT(int bytes, int documentOptions) → document *
This message creates a new, empty document and returns a pointer to it. This document is not selected into the editor and starts with a reference count of 1. This means that you have ownership of it and must either reduce its reference count by 1 after using @@ -5743,12 +5744,29 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ to allocate once rather than rely on the buffer growing as data is added. If SCI_CREATEDOCUMENT fails then 0 is returned.

-

The documentOption argument +

The documentOptions argument chooses between different document capabilities which affect memory allocation and performance with SC_DOCUMENTOPTION_DEFAULT (0) choosing standard options. - SC_DOCUMENTOPTION_STYLES_NONE (1) stops allocation of memory to style characters + SC_DOCUMENTOPTION_STYLES_NONE (0x1) stops allocation of memory to style characters which saves significant memory, often 40% with the whole document treated as being style 0. - Lexers may still produce visual styling by using indicators.

+ Lexers may still produce visual styling by using indicators. + SC_DOCUMENTOPTION_TEXT_LARGE (0x100) accomodates documents larger than 2 GigaBytes + in 64-bit executables. +

+ +

With SC_DOCUMENTOPTION_STYLES_NONE, lexers are still active and may display + indicators. Some may produce folding information althoough most require lexical styles to correctly determine folding. + Its often more efficient to set the null lexer SCLEX_NULL so no lexer is run. +

+ +

The SC_DOCUMENTOPTION_TEXT_LARGE option is experimental and has not been + thoroughly tested. Lexers may fail or hang when lexing past 2GB or 4GB. + Applications using this option should be tested to ensure the option works in their circumstances and each lexer + included should also be tested with documents larger than 4GB. + For many applications lexing documents larger than 4GB will be too sluggish so SC_DOCUMENTOPTION_STYLES_NONE + and the null lexer SCLEX_NULL can be used. Another approach is to turn on idle styling with + SCI_SETIDLESTYLING. +

@@ -5769,10 +5787,16 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ - + + + + + + +
SC_DOCUMENTOPTION_STYLES_NONE10x1 Stop allocation of memory for styles and treat all text as style 0.
SC_DOCUMENTOPTION_TEXT_LARGE0x100Allow document to be larger than 2 GB.
@@ -5794,6 +5818,9 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ world spinning in its orbit you must balance each call to SCI_CREATEDOCUMENT or SCI_ADDREFDOCUMENT with a call to SCI_RELEASEDOCUMENT.

+

SCI_GETDOCUMENTOPTIONS → int
+ Returns the options that were used to create the document.

+

Background loading and saving

To ensure a responsive user interface, applications may decide to load and save documents using a separate thread @@ -5801,7 +5828,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){

Loading in the background

- SCI_CREATELOADER(int bytes, int documentOption) → int
+ SCI_CREATELOADER(int bytes, int documentOptions) → int

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 @@ -5810,15 +5837,15 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){

To avoid these issues, a loader object may be created and used to load the file. The loader object supports the ILoader interface.

-

SCI_CREATELOADER(int bytes, int documentOption) → int
+

SCI_CREATELOADER(int bytes, int documentOptions) → int
Create an object that supports the ILoader interface which can be used to load data and then be turned into a Scintilla document object for attachment to a view object. The bytes 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 SCI_CREATELOADER fails then 0 is returned.

-

The documentOption argument - is described in the SCI_CREATEDOCUMENT section.

+

The documentOptions argument + is described in the SCI_CREATEDOCUMENT section.

ILoader

-- cgit v1.2.3