学步园

Last edited18/January/2013 NH

Thereis an overview of the internal design of Scintilla.Scintilla内部设计的概述
Some notes on using Scintilla.使用Scintilla的一些注意事项

How to use the Scintilla Edit Control on Windows.在Windows上如何使用ScintillaEdit Control
A simple sample using Scintilla from C++ on Windows.Windows一个简单的使用Scintilla的例子（C++）
A simple sample using Scintilla from Visual Basic.Windows一个简单的使用Scintilla的例子（Visual Basic）
Bait is a tiny sample using Scintilla on GTK+.Bait，这是一个简单的在GTK+中使用Scintilla的例子
A detailed description of how to write a lexer, includinga discussion of folding.详述如何编写一个语法识别器，包括代码折叠的详细讨论
How to implement a lexer in the container.如何在容器中实现一个语法识别器
How to implement folding.如何实现代码折叠
The codingstyle used in Scintilla and SciTE is worthfollowing if you want to contribute code to Scintilla but is not compulsory.

Introduction介绍

TheWindows version of Scintilla is a Windows Control. As such, its primaryprogramming interface is through Windows messages. Early versions of Scintillaemulated much of the API defined by the standard Windows Edit and RichEditcontrols but those
APIs are now deprecated in favour of Scintilla's own, moreconsistent API. In addition to messages performing the actions of a normal Editcontrol, Scintilla allows control of syntax styling, folding, markers,autocompletion and call tips.

Window版本的Scintilla是一个WindowsControl。因此，其主要的开发接口都是通过Windows消息来实现的。早期版本的Scintilla模仿Windows的Edit控件和RichEdit控件，定义了大量的API，但是现在这些API都已经不再推荐使用，他们已经被现在Scintilla的更一致的API取代。除了一般的Edit Control的功能外，Scintill还支持语法样式，代码折叠，标签，自动完成，以及函数调用提示。

TheGTK+ version also uses messages in a similar way to the Windows version. Thisis different to normal GTK+ practice but made it easier to implement rapidly.

GTK+版本的Scintilla也是采用的和Windows下的类似消息通讯机制。这一点和一般的GTK+惯例有些不同，但是这可以让实现更加简单快速。

Scintilladoes not properly support right-to-left languages like Arabic and Hebrew. Whiletext in these languages may appear correct, it is not possible to interact withthis text as is normal with other editing components.

Scintilla对从右至左布局的语言支持得不好，比如阿拉伯语和希伯来语。所以，这些语言的文字可能会显示正常，但可能无法与其他功能正常工作。

Thisdocumentation describes the individual messages and notifications used byScintilla. It does not describe how to link them together to form a usefuleditor. For now, the best way to work out how to develop using Scintilla is tosee how SciTE
uses it. SciTE exercises most of Scintilla's facilities.

这篇文档描述了Scintilla中的单个的消息和通知事件。但不会去描述如何将这些功能集成到一起以组成一个使用的编辑器。于是，最好的学习如何使用Scintilla做开发的办法就是参考SciTE是如何使用的。SciTE使用到了Scintilla的绝大多数特性。

Inthe descriptions that follow, the messages are described as function calls withzero, one or two arguments. These two arguments are the standard wParam and lParam familiarto Windows programmers. These parameters
are integers that are large enough tohold pointers, and the return value is also an integer large enough to containa pointer. Although the commands only use the arguments described, because allmessages have two arguments whether Scintilla uses them or not,
it is stronglyrecommended that any unused arguments are set to 0. This allows futureenhancement of messages without the risk of breaking existing code. Commonargument types are:

这里的两个参数和Windows下的其他程序类似是标准的wParam and lParam 。这些参数都是一个足够存下一个执政的整数，而返回值也是如此。虽然有些指令（Commands）都没使用任何参数，但是所有的消息都会带两个参数，不管Scintilla内部是否使用它们，我们强烈建议大家对于未用到的参数统一设置为0。这可以避免当某些消息在新特性，破坏现有代码的行为。通用的参数类型是：

Contents

Messageswith names of the form SCI_SETxxxxx oftenhave a companion SCI_GETxxxxx. To save tediousrepetition, if theSCI_GETxxxxx messagereturns the value set by the SCI_SETxxxxx message,the SET routineis
described and the GET routineis left to your imagination.

类似SCI_SETxxxxx 的消息通常也会有一个对应的SCI_GETxxxxx消息。为了保持一致性，SCI_GETxxxxx的返回值就是SCI_SETxxxxx 设置的值，只要你看到一个SET你就应该想到会有一个对应的GET。

Text retrieval andmodification

文本获取和修改

Each byte in a Scintilladocument is followed by an associated byte of styling information. Thecombination of a character byte and a style byte is called a cell. Style bytesare interpreted an index into an array of styles. Style bytes may
be split intoan index and a set of indicator bits but this use is discouraged and indicatorsshould now useSCI_INDICATORFILLRANGE and
related calls. Thedefault split is with the index in the low 5 bits and 3 high bits asindicators.
This allows 32fundamental styles, which is enough for most languages, and three independentindicators so that, for example, syntax errors, deprecated names and badindentation could all be displayed at once. The number of bits used for stylescan be altered
with SCI_SETSTYLEBITS up to a maximum of 8bits.
The remaining bits can be used for indicators.

Scintilla文档中的每个字节，都会关联一个Style信息。一个字节及其Style的组合叫做一个cell。字节Style实际是一个Style列表的索引。一个字节Style可能会被分为一个索引编号和一系列标记位，标记位现在已经不推荐大家使用，我们现在使用SCI_INDICATORFILLRANGE和其关联的cell。缺省的分割方法为Style索引的低5bit和高3bit作为标记位。这就允许32中基本的Style。对大多数语言来说这个已经足够了。还有三个标记位跟这个无关，通常用于及时显示一些信息，比如，语法错误，不推荐的名字和缩进错误等。具体多少位可用于Style，可以用SCI_SETSTYLEBITS来设置，最大支持8bit。其他的bit位都用于表示标记。

[MS1] Inthis document, 'character'
normally refers to a byte even when multi-bytecharacters are used. Lengths measure the numbers of bytes, not the amount ofcharacters in those bytes.

在本文中，‘字符’通常是指字节，即使我们用的是多字节的字符。长度也指的是字节的个数，而不是指这些字节中有多少字符。

Positions withinthe Scintilla document refer to a character or the gap before that character.The first character in a document is 0, the second 1 and so on. If a documentcontains nLen characters, thelast character is numbered nLen-1.
The caret exists between character positions and can be located frombefore the first character (0) to after the last character (nLen).

Scintilla中的位置信息涉及到字符以及字符之间的间隙。一个文档中的第一个字符的位置是0，第二个字符的位置是1，以此类推。如果一个文档包含nLen个字符，那么最后一个字符的位置就是nLen-1。连字符可以出现的位置是从第一个字符（0）到最后一个字符(nLen)。

Thereare places where the caret can not go where two character bytes make up onecharacter. This occurs when a DBCS character from a language like Japanese isincluded in the document or when line ends are marked with the CP/M standard ofa carriage
return followed by a line feed. The INVALID_POSITION constant(-1) represents an invalid position within the document.

有些场景下连字符不能出现在两个字符之间，比如当两个字节实际上是一个字符时。这种情况出现在当文档包含一些DBCS字符时，比如日语字符，或者行尾被标记为xxxxx[MS2] 。常量INVALID_POSITION （-1）表示文档中的无效位置。

Alllines of text in Scintilla are the same height, and this height is calculatedfrom the largest font in any current style. This restriction is forperformance; if lines differed in height then calculations involvingpositioning of text would
require the text to be styled first.

Scintilla中的所有行中的文本都具有相同的行高，而且这个行高是所有的Stlye的字体中最大的那个。这样做性能会高一些。如果各行的行高都不相同，那么计算某个文本的位置就要从第一个文本的Style开始算起。

SCI_GETTEXT(intlength, char *text)
SCI_SETTEXT(<unused>,const char *text)
SCI_SETSAVEPOINT
SCI_GETLINE(intline, char *text)
SCI_REPLACESEL(<unused>,const char *text)
SCI_SETREADONLY(boolreadOnly)
SCI_GETREADONLY
SCI_GETTEXTRANGE(<unused>,Sci_TextRange *tr)
SCI_ALLOCATE(intbytes, <unused>)
SCI_ADDTEXT(intlength, const char *s)
SCI_ADDSTYLEDTEXT(intlength, cell *s)
SCI_APPENDTEXT(intlength, const char *s)
SCI_INSERTTEXT(intpos, const char *text)
SCI_CLEARALL
SCI_DELETERANGE(intpos, int deleteLength)
SCI_CLEARDOCUMENTSTYLE
SCI_GETCHARAT(intposition)
SCI_GETSTYLEAT(intposition)
SCI_GETSTYLEDTEXT(<unused>,Sci_TextRange *tr)
SCI_SETSTYLEBITS(intbits)
SCI_GETSTYLEBITS
SCI_RELEASEALLEXTENDEDSTYLES
SCI_ALLOCATEEXTENDEDSTYLES(intnumberStyles)
SCI_TARGETASUTF8(<unused>,char *s)
SCI_ENCODEDFROMUTF8(constchar *utf8, char *encoded)
SCI_SETLENGTHFORENCODE(intbytes)

SCI_GETTEXT(intlength, char *text)
This returns length-1 characters of textfrom the start of the document plus one terminating 0 character. To collect allthe text in a document, use SCI_GETLENGTH toget the number of characters
in the document (nLen), allocate a characterbuffer of length nLen+1 bytes,then call SCI_GETTEXT(nLen+1,char *text). If the text argument is 0 then thelength that should be allocated to store the entire document
is returned. Ifyou then save the text, you should use SCI_SETSAVEPOINT tomark the text as unmodified.

该函数返回的数据时从文本的起始位置返回length-1个字符，并以0字符结尾。如果想获取文档中的所有文本，需要先用SCI_GETLENGTH 获取文档中总共有多少字符（nLen），然后分配nLen+1 字节的缓冲区，接着再调用SCI_GETTEXT(nLen+1, char*text)。如果text参数为0，那么整个文档的的数据自动分配内存兵返回。如果你已经保存了text，你应该使用SCI_SETSAVEPOINT 来标注text没有修改。

See also: SCI_GETSELTEXT, SCI_GETCURLINE, SCI_GETLINE, SCI_GETSTYLEDTEXT, SCI_GETTEXTRANGE

SCI_SETTEXT(<unused>,const char *text)
This replaces all the text in the document with the zero terminated text stringyou pass in.

这个接口会用一个以0结尾的字符串作为输入参数的文本来替换掉整个文档的内容。

SCI_SETSAVEPOINT
This message tells Scintilla that the currentstate of the document is unmodified. This is usually done when the file issaved or loaded, hence the name "save point". As Scintilla performsundo and redo operations, it notifies the
container that it has entered or leftthe save point with SCN_SAVEPOINTREACHED and SCN_SAVEPOINTLEFT notificationmessages,
allowing the container to know if thefile should be considered dirty or not.

这个消息用来告诉Scintilla，当前文档是没有修改的。通常在保存完毕和刚加载完文件是需要这么处理，这就是所谓的“sacepoint”。在Scintilla执行undo和redo操作时，将用SCN_SAVEPOINTREACHED和 SCN_SAVEPOINTLEFT通知消息来通知容器，Scintilla已经进入或者离开svaepoint。这样便于container知道当前文件是否是“脏”[MS3] 的。

See also: SCI_EMPTYUNDOBUFFER, SCI_GETMODIFY

SCI_GETLINE(intline, char *text)
This fills the buffer defined by text with the contents of the nominated line(lines start at 0). The buffer is not terminated by a 0 character. It is up toyou to make sure that the buffer is long enough for the text, useSCI_LINELENGTH(int
line).The returned value is the number of characters copied to the buffer. Thereturned text includes any end of line characters. If you ask for a line numberoutside the range of lines in the document, 0 characters are copied. If
thetext argument is 0 then the length that should be allocated to store the entireline is returned.

本函数用指定的行（从0开始）的内容来填充text参数指向的缓冲区。填充的内容不是以字符0结尾。调用前你必须保证缓冲区的长度足够容纳下该行的文本。可以通过SCI_LINELENGTH(int
line)来获取指定行的长度。返回值表示缓冲区中填充料多少字符。返回的文本将包括行结束符。如果line参数指定的行超出本文档行号的范围，0个字符将被拷贝。如果text参数为0，Scintilla将自动分配足够存储该行长度的缓冲区，并返回。

See also: SCI_GETCURLINE, SCI_GETSELTEXT, SCI_GETTEXTRANGE, SCI_GETSTYLEDTEXT, SCI_GETTEXT

SCI_REPLACESEL(<unused>,const char *text)
The currently selected text between the anchorand the current position isreplaced
by the 0 terminated text string. If the anchor and current positionare the same, the text is inserted at the caret position. The caret ispositioned after the inserted text and the caret is scrolled into view.

本函数用text参数所指向的以0结尾的字符串，来替换由 anchorand
和currentposition指向当前选中的文本。如果anchor和current position相等，那么就表示插入文本到caretposition。xxxxx[MS4] 

SCI_SETREADONLY(boolreadOnly)
SCI_GETREADONLY
These messages set and get the read-only flagfor the document. If you mark a document as read only, attempts to modify thetext cause the SCN_MODIFYATTEMPTRO notification.

这些消息用来设置文档的read-only标记。如果文档被标记为read-only的，那么试图对文本进行修改时，会触发SCN_MODIFYATTEMPTRO通知。

SCI_GETTEXTRANGE(<unused>, Sci_TextRange *tr)
This collects the text between the positions cpMin and cpMax andcopies it to lpstrText (see struct Sci_TextRange inScintilla.h). If cpMax is-1, text is returned
to the end of the document. The text is 0 terminated, soyou must supply a buffer that is at least 1 character longer than the number ofcharacters you wish to read. The return value is the length of the returnedtext not including the terminating 0.

这个会将从cpMin 到cpMax 这两个位置间的文本，拷贝到lpstrText （参见Scintilla.h 中的struct Sci_TextRange定义）。如果cpMax等于-1，返回一直到文档结束位置的文本。返回的文本以0结尾，所以你必须缓冲区的长度必须必你想要读取的内容要多至少1字符。返回值表示实际包含的字符数，不含尾部的0字符。

See also: SCI_GETSELTEXT, SCI_GETLINE, SCI_GETCURLINE, SCI_GETSTYLEDTEXT, SCI_GETTEXT

SCI_GETSTYLEDTEXT(<unused>, Sci_TextRange *tr)
This collects styled text into a buffer using two bytes for each cell, with thecharacter at the lower address of each pair and the style byte at the upperaddress. Characters between the positions cpMin and cpMax are copied
to lpstrText (seestruct Sci_TextRange in Scintilla.h). Two 0 bytes are added to the end of the text, so thebuffer that lpstrText points at must beat least 2*(cpMax-cpMin)+2 bytes
long. Nocheck is made for sensible values of cpMin or cpMax. Positionsoutside the document return character codes and style bytes of 0.

See also: SCI_GETSELTEXT, SCI_GETLINE, SCI_GETCURLINE, SCI_GETTEXTRANGE, SCI_GETTEXT

SCI_ALLOCATE(intbytes, <unused>)
Allocate a document buffer large enough to store a given number of bytes. Thedocument will not be made smaller than its current contents.

分配一个bytes参数指定的大小的文档缓冲区。文档不会因此而变得比当前的内容更小。[MS5] 

SCI_ADDTEXT(intlength, const char *s)
This inserts the first length charactersfrom the string s atthe current position. This will include any 0's in the string that you mighthave expected to stop the insert operation. The current position is set at theend of the
inserted text, but it is not scrolled into view.

这个将由s指向的长length 的文本插入到当前position。这个函数在遇到任何\0字符时将停止插入操作。插入完成后，当前的位置将调整到插入文本之后。而且不要指望Scintilla会自动滚动视图使其显示。

SCI_ADDSTYLEDTEXT(intlength, cell *s)
This behaves just like SCI_ADDTEXT, but inserts styledtext.

这个的行为和SCI_ADDTEXT类似，但是插入的是带Style的文本。

SCI_APPENDTEXT(intlength, const char *s)
This adds the first length charactersfrom the string s tothe end of the document. This will include any 0's in the string that you mighthave expected to stop the operation. The current selection is not changed andthe new text
is not scrolled into view.

这个函数，会将由s指向的长为length的字符串添加到文档的结尾。遇到任何\0字符，都将终止该插入操作。当前选中的文本不会因此而改变，Scintilla也不会自动滚动窗口让新插入的文本显示出来。

SCI_INSERTTEXT(intpos, const char *text)
This inserts the zero terminated text stringat position pos orat the current position if pos is-1. If the current position is after the insertion point then it is moved alongwith its surrounding text but no
scrolling is performed.

将有text参数指定的\0结束的文本插入到pos指定的位置，如果pos为-1，表示插入到当前位置。如果当前位置在插入点之后，那么当前位置也会跟着移动移动，但不会滚动视图使其显示。

SCI_CLEARALL
Unless the document is read-only, this deletes all the text.

他将删除文档中的所有文本，除非文档是只读的。

SCI_DELETERANGE(intpos, int deleteLength)
Deletes a range of text in the document.

删除文档中指定范围内的文本。

SCI_CLEARDOCUMENTSTYLE
When wanting to completely restyle the document, for example after choosing alexer, the SCI_CLEARDOCUMENTSTYLE canbe used to clear all styling information and reset the folding state.

如果你向完全重置整个文档的Style，比如当用户切换了一个新的lexer时，SCI_CLEARDOCUMENTSTYLE 就可以用来清除所有的Style信息，并且重置所有的代码折叠状态。

SCI_GETCHARAT(intpos)
This returns the character at pos inthe document or 0 if pos isnegative or past the end of the document.

这个返回pos指向的字符，当pos为负或者文档的范围时，返回0。

SCI_GETSTYLEAT(intpos)
This returns the style at pos inthe document, or 0 if pos isnegative or past the end of the document.

这个返回pos指向的位置的Style。当pos为负或者文档的范围时，返回0。

SCI_SETSTYLEBITS(intbits)
SCI_GETSTYLEBITS
This pair of routines sets and reads back the number of bits in each cell touse for styling, to a maximum of 8 style bits. The remaining bits can be usedas indicators. The standard setting is SCI_SETSTYLEBITS(5). The number of styling bits
needed by thecurrent lexer can be found with SCI_GETSTYLEBITSNEEDED.

SCI_RELEASEALLEXTENDEDSTYLES
SCI_ALLOCATEEXTENDEDSTYLES(int numberStyles)
Extended styles are used for features like textual margins and annotations aswell as internally by Scintilla. They are outside the range 0..255 used for thestyles bytes associated with document bytes. These functions manage the use ofextended styles to ensures
that components cooperate in defining styles. SCI_RELEASEALLEXTENDEDSTYLES releases anyextended styles allocated by the container. SCI_ALLOCATEEXTENDEDSTYLES allocates a rangeof style numbers after the byte style values and
returns the number of thefirst allocated style. Ranges for margin and annotation styles should beallocated before calling SCI_MARGINSETSTYLEOFFSET or SCI_ANNOTATIONSETSTYLEOFFSET.

Sci_TextRange and Sci_CharacterRange
These structures are defined to be exactly thesame shape as the Win32 TEXTRANGE and CHARRANGE, so that older codethat treats Scintilla as a RichEdit will work.

这个结构实际上与WIN32下的TEXTRANGE 和 CHARRANGE相同，所以有些比较老的代码将Scintilla当做RichEdit来玩也可以工作。

struct Sci_CharacterRange {

   long cpMin;

   long cpMax;

};

struct Sci_TextRange {

   struct Sci_CharacterRange chrg;

   char *lpstrText;

};

GTK+-specific:Access to encoded text

SCI_TARGETASUTF8(<unused>,char *s)
This method retrieves the value of the target encoded as UTF-8 which is thedefault encoding of GTK+ so is useful for retrieving text for use in otherparts of the user interface, such as find and replace dialogs. The length ofthe encoded text in bytes is returned.

SCI_ENCODEDFROMUTF8(constchar *utf8, char *encoded)
SCI_SETLENGTHFORENCODE(int bytes)
SCI_ENCODEDFROMUTF8 converts a UTF-8string into the document's encoding which is useful for taking the results of afind dialog, for example, and receiving a string of bytes that can be searchedfor in the document. Since the text can contain nul bytes,
the SCI_SETLENGTHFORENCODE method can be usedto set the length that will be converted. If set to -1, the length isdetermined by finding a nul byte. The length of the converted string isreturned.