From 8fe23071ec3f82bf2b602f2ba5edee0cf6bc6fa3 Mon Sep 17 00:00:00 2001 From: Neil Date: Mon, 17 Jul 2017 14:21:40 +1000 Subject: Documentation for style metadata. --- doc/ScintillaDoc.html | 110 +++++++++++++++++++++----------------------------- 1 file changed, 45 insertions(+), 65 deletions(-) (limited to 'doc/ScintillaDoc.html') diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index a04205387..c669d3c40 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -6763,7 +6763,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ purpose would exhaust the number of allowed styles quickly. This is alleviated by substyles which allow the application to determine how many sets of identifiers to allocate for each purpose. - Lexers have to explicitly support this feature by implementing the methods in ILexerWithSubStyles.

+ Lexers have to explicitly support this feature by implementing particular methods.

SCI_GETSUBSTYLEBASES(<unused>, char *styles NUL-terminated) → int
Fill styles with a byte for each style that can be split into substyles.

@@ -6797,7 +6797,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){

Lexer Objects

-

Lexers are programmed as objects that implement the ILexer interface and that interact +

Lexers are programmed as objects that implement the ILexer4 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 @@ -6805,48 +6805,36 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ 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

+

ILexer4

-class ILexer {
+class ILexer4 {
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 - Sci_Position SCI_METHOD - PropertySet(const char *key, const char *val) = 0;
-    virtual - const char * SCI_METHOD - DescribeWordListSets() = 0;
-    virtual - Sci_Position SCI_METHOD - WordListSet(int n, const char *wl) = 0;
-    virtual - void SCI_METHOD - Lex(Sci_PositionU startPos, Sci_Position lengthDoc, int initStyle, IDocument *pAccess) = 0;
-    virtual - void SCI_METHOD - Fold(Sci_PositionU startPos, Sci_Position lengthDoc, int initStyle, IDocument *pAccess) = 0;
-    virtual - void * SCI_METHOD - PrivateCall(int operation, void *pointer) = 0;
+        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 Sci_Position SCI_METHOD PropertySet(const char *key, const char *val) = 0;
+        virtual const char * SCI_METHOD DescribeWordListSets() = 0;
+        virtual Sci_Position SCI_METHOD WordListSet(int n, const char *wl) = 0;
+        virtual void SCI_METHOD Lex(Sci_PositionU startPos, Sci_Position lengthDoc, int initStyle, IDocument *pAccess) = 0;
+        virtual void SCI_METHOD Fold(Sci_PositionU startPos, Sci_Position lengthDoc, int initStyle, IDocument *pAccess) = 0;
+        virtual void * SCI_METHOD PrivateCall(int operation, void *pointer) = 0;
+        virtual int SCI_METHOD LineEndTypesSupported() = 0;
+        virtual int SCI_METHOD AllocateSubStyles(int styleBase, int numberStyles) = 0;
+        virtual int SCI_METHOD SubStylesStart(int styleBase) = 0;
+        virtual int SCI_METHOD SubStylesLength(int styleBase) = 0;
+        virtual int SCI_METHOD StyleFromSubStyle(int subStyle) = 0;
+        virtual int SCI_METHOD PrimaryStyleFromStyle(int style) = 0;
+        virtual void SCI_METHOD FreeSubStyles() = 0;
+        virtual void SCI_METHOD SetIdentifiers(int style, const char *identifiers) = 0;
+        virtual int SCI_METHOD DistanceToSecondaryStyles() = 0;
+        virtual const char * SCI_METHOD GetSubStyleBases() = 0;
+        virtual int SCI_METHOD NamedStyles() = 0;
+        virtual const char * SCI_METHOD NameOfStyle(int style) = 0;
+        virtual const char * SCI_METHOD TagsOfStyle(int style) = 0;
+        virtual const char * SCI_METHOD DescriptionOfStyle(int style) = 0;
};
@@ -6855,6 +6843,12 @@ The types Sci_Position and Sci_PositionU are used for With Scintilla 4, 64-bit builds define these as 64-bit types to allow future implementation of documents larger than 2 GB.

+

+Methods that return strings as const char * are not required to maintain separate allocations indefinitely: +lexer implementations may own a single buffer that is reused for each call. +Callers should make an immediate copy of returned strings. +

+

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 @@ -6864,7 +6858,7 @@ optimisation could be to remember where a setting first affects the document and

Version returns an enumerated value specifying which version of the interface is implemented: -lvOriginal for ILexer and lvSubStyles for ILexerWithSubStyles.

+lvRelease4 for ILexer4. Prior to Scintilla 4.0 different values were possible.

Release is called to destroy the lexer object.

@@ -6882,29 +6876,15 @@ needs to be folded as this allowed fixing up the last line from the previous fol The new approach allows the lexer to decide whether to backtrack or to handle this more efficiently.

-

ILexerWithSubStyles

- -

-To allow lexers to report which line ends they support, and to support substyles, -Ilexer is extended to ILexerWithSubStyles. +

NamedStyles, NameOfStyle, +TagsOfStyle, and DescriptionOfStyle +are used to provide information on the set of styles used by this lexer. +NameOfStyle is the C-language identifier like "SCE_LUA_COMMENT". +TagsOfStyle is a set of tags describing the style in a standardized way like "literal string multiline raw". +A set of common tags and conventions for combining them is described here. +DescriptionOfStyle is an English description of the style like "Function or method name definition".

-
-class ILexerWithSubStyles : public ILexer {
-public:
-        virtual int SCI_METHOD LineEndTypesSupported() = 0;
-        virtual int SCI_METHOD AllocateSubStyles(int styleBase, int numberStyles) = 0;
-        virtual int SCI_METHOD SubStylesStart(int styleBase) = 0;
-        virtual int SCI_METHOD SubStylesLength(int styleBase) = 0;
-        virtual int SCI_METHOD StyleFromSubStyle(int subStyle) = 0;
-        virtual int SCI_METHOD PrimaryStyleFromStyle(int style) = 0;
-        virtual void SCI_METHOD FreeSubStyles() = 0;
-        virtual void SCI_METHOD SetIdentifiers(int style, const char *identifiers) = 0;
-        virtual int SCI_METHOD DistanceToSecondaryStyles() = 0;
-        virtual const char * SCI_METHOD GetSubStyleBases() = 0;
-};
-
-

IDocument

@@ -6967,8 +6947,8 @@ The pWidth argument can be NULL if the caller doe bytes in the character.

-

The ILexer, ILexerWithSubStyles, and IDocument interfaces may be -expanded in the future with extended versions (ILexer2...). +

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

-- cgit v1.2.3