From 74f2d921081d703edda74c7925b76f9176c32db2 Mon Sep 17 00:00:00 2001 From: nyamatongwe Date: Sun, 4 Dec 2011 12:09:13 +1100 Subject: Document background loading and saving. --- doc/ScintillaDoc.html | 71 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 64 insertions(+), 7 deletions(-) (limited to 'doc/ScintillaDoc.html') 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 @@ + o Background loading and saving + o Folding o Line wrapping - - o Zooming + o Zooming + o Long lines o Lexer - - o Lexer objects + o Lexer objects + o Notifications o Images - - o GTK+ + o GTK+ + o Deprecated messages o Edit messages never supported by Scintilla - o Building Scintilla + + + o Building Scintilla @@ -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 SCI_CREATEDOCUMENT or SCI_ADDREFDOCUMENT with a call to SCI_RELEASEDOCUMENT.

+

Background loading and saving

+ +

To ensure a responsive user interface, applications may decide to load and save documents using a separate thread + from the user interface.

+ +

Loading in the background

+ +

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.

+ +

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)
+ 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.

+ +

ILoader

+ +
+class ILoader {
+public:
+        virtual int SCI_METHOD Release() = 0;
+        // Returns a status code from SC_STATUS_*
+        virtual int SCI_METHOD AddData(char *data, int length) = 0;
+        virtual void * SCI_METHOD ConvertToDocument() = 0;
+};
+
+ +

The application should call the AddData method with each block of data read from the file. + AddData will return SC_STATUS_OK unless a failure, such as memory exhaustion occurs. + 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, the ConvertToDocument method should be called to produce a Scintilla + document pointer which can be used in the same way as a document pointer returned from + SCI_CREATEDOCUMENT. + There is no need to call Release after ConvertToDocument.

+ +

Saving in the background

+ +

An application that wants to save in the background should lock the document with SCI_SETREADONLY(1) + to prevent modifications and retrieve a pointer to the unified document contents with + SCI_GETCHARACTERPOINTER. + The buffer of a locked document will not move so the pointer is valid until the application calls SCI_SETREADONLY(0).

+ +

If the user tries to performs a modification while the document is locked then a SCN_MODIFYATTEMPTRO 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.

+

Folding

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