From d28ffde2997be8a01ed9cff79e1575ad22c4f6f5 Mon Sep 17 00:00:00 2001 From: nyamatongwe Date: Fri, 16 Jul 2010 20:47:32 +1000 Subject: Lexer objects documentation. --- doc/ScintillaDoc.html | 335 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 319 insertions(+), 16 deletions(-) (limited to 'doc/ScintillaDoc.html') diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index 0f22dd849..07c3c0aeb 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -14,12 +14,53 @@ @@ -38,7 +79,7 @@

Scintilla Documentation

-

Last edited 26/June/2010 NH

+

Last edited 16/July/2010 NH

There is an overview of the internal design of Scintilla.
@@ -262,20 +303,20 @@ o Lexer - o Notifications + o Lexer objects + o Notifications + o GTK+ o Deprecated messages - - o Edit messages never - supported by Scintilla - + o Edit messages never + supported by Scintilla o Building Scintilla @@ -5190,14 +5231,14 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){

Lexer

If you define the symbol SCI_LEXER when building Scintilla, (this is sometimes - called the SciLexer version of Scintilla), lexing support for a wide range programming + called the SciLexer version of Scintilla), lexing support for a wide range of programming languages is included and the messages in this section are supported. If you want to set styling and fold points for an unsupported language you can either do this in the container or better still, write your own lexer following the pattern of one of the existing ones.

-

Scintilla also supports external lexers. These are DLLs (on Windows) or .so modules (on GTK+/Linux) that export four - functions: GetLexerCount, GetLexerName, Lex and - Fold. See externalLexer.cxx for more.

+

Scintilla also supports external lexers. These are DLLs (on Windows) or .so modules (on GTK+/Linux) that export three + functions: GetLexerCount, GetLexerName, and + GetLexerFactory. See externalLexer.cxx for more.

SCI_SETLEXER(int lexer)
SCI_GETLEXER
SCI_SETLEXERLANGUAGE(<unused>, const char @@ -5360,6 +5401,268 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ to SCI_SETSTYLEBITS.

+

Lexer Objects

+ +

Lexers are programmed as objects that implement the ILexer interface and that interact + with the document they are lexing through the IDocument interface. + Previously lexers were defined by providing lexing and folding functions but creating an object + to handle the interaction of a lexer with a document allows the lexer to store state information that + can be used during lexing. For example a C++ lexer may store a set of preprocessor definitions + or variable declarations and style these depending on their role.

+ +

A set of helper classes allows older lexers defined by functions to be used in Scintilla.

+

ILexer

+ +
+class ILexer {
+public:
+    virtual + int SCI_METHOD + Version() +const = + 0;
+    virtual + void SCI_METHOD + Release() += 0;
+    virtual +const +char +* +SCI_METHOD PropertyNames() + = 0;
+    virtual + int SCI_METHOD PropertyType(const char *name) = 0;
+    virtual + const char * SCI_METHOD DescribeProperty(const char *name) = 0;
+    virtual + int SCI_METHOD + PropertySet(const + char + *key, + const +char *val) + = + 0;
+    virtual +const char +* SCI_METHOD DescribeWordListSets() + = +0;
+    virtual + int SCI_METHOD + WordListSet(int + n, + const +char *wl) + = + 0;
+    virtual + void SCI_METHOD + Lex(unsigned + int + startPos, + int + lengthDoc, +int initStyle, + IDocument +*pAccess) + = +0;
+    virtual + void SCI_METHOD + Fold(unsigned + int startPos, + int + lengthDoc, +int initStyle, + IDocument +*pAccess) + = +0;
+    virtual + void +* SCI_METHOD +PrivateCall(int + operation, +void +*pointer) += 0;
+};
+
+ +

+The return values from PropertySet and WordListSet are used to indicate whether the change requires +performing lexing or folding over any of the document. It is the position at which to restart lexing and folding or -1 +if the change does not require any extra work on the document. +A simple approach is to return 0 if there is any possibility that a change requires lexing the document again while an +optimisation could be to remember where a setting first affects the document and return that position. +

+ +

Release is called to destroy the lexer object.

+ +

PrivateCall allows for direct communication between the +application and a lexer. An example would be where an application +maintains a single large data structure containing symbolic information +about system headers (like Windows.h) and provides this to the lexer +where it can be applied to each document. This avoids the costs of +constructing the system header information for each document. This is +invoked with the SCI_PRIVATELEXERCALL API.

+ + +

IDocument

+ +
+class IDocument + {
+public:
+    virtual + int SCI_METHOD + Version() +const = + 0;
+    virtual + void SCI_METHOD + SetErrorStatus(int + status) + = +0;
+    virtual + int SCI_METHOD + Length() +const = + 0;
+    virtual + void SCI_METHOD + GetCharRange(char + *buffer, + int +position, +int lengthRetrieve) + const + = +0;
+    virtual + char SCI_METHOD + StyleAt(int + position) +const = + 0;
+    virtual + int SCI_METHOD + LineFromPosition(int position) + const = + 0;
+    virtual +int SCI_METHOD + LineStart(int line) + const = + 0;
+    virtual +int SCI_METHOD + GetLevel(int line) + +const = +0;
+    virtual +int SCI_METHOD + SetLevel(int + line, +int level) + = +0;
+    virtual + int SCI_METHOD + GetLineState(int + line) + const += 0 +;
+    virtual + int SCI_METHOD + SetLineState(int + line, + int state) + = + 0;
+    virtual + void SCI_METHOD + StartStyling(int + position, + char mask) + = + 0;
+    virtual bool + SCI_METHOD + SetStyleFor(int + length, + char style) + = 0 +;
+     virtual + bool SCI_METHOD + SetStyles(int + length, +const char + *styles) + = +0;
+    virtual void + SCI_METHOD + DecorationSetCurrentIndicator(int + indicator) + = + 0;
+    virtual + void SCI_METHOD + DecorationFillRange(int + position, + int value, + int fillLength) + + = +0;
+    virtual + void SCI_METHOD + ChangeLexerState(int + start, + int end) + = + 0;
+    virtual + int SCI_METHOD + CodePage() + const += 0 +;
+    virtual bool + SCI_METHOD + IsDBCSLeadByte(char + ch) + const = + 0;
+};
+
+ +

Scintilla tries to minimize the consequences of modifying text to +only relex and redraw the line of the change where possible. Lexer +objects contain their own private extra state which can affect later +lines. For example, if the C++ lexer is greying out inactive code +segments then changing the statement #define BEOS 0 to #define + BEOS 1 may require restyling and redisplaying later parts of the + document. The lexer can call ChangeLexerState to signal to + the document that it should relex and display more.

+ +

SetErrorStatus is used to notify the document of +exceptions. Exceptions should not be thrown over build boundaries as the + two sides may be built with different compilers or incompatible +exception options.

+ +

The ILexer and IDocument interfaces may be +expanded in the future with extended versions (ILexer2...). + The Version method indicates which interface is +implemented and thus which methods may be called.

+

Notifications

Notifications are sent (fired) from the Scintilla control to its container when an event has -- cgit v1.2.3