scintilladoc.html

最强源代码编辑控件

        <tr>
          <td>o <a class="toc" href="#MultipleViews">Multiple views</a></td>

          <td>o <a class="toc" href="#Folding">Folding</a></td>

          <td>o <a class="toc" href="#LineWrapping">Line wrapping</a></td>
        </tr>

        <tr>
          <td>o <a class="toc" href="#Zooming">Zooming</a></td>

          <td>o <a class="toc" href="#LongLines">Long lines</a></td>

          <td>o <a class="toc" href="#Lexer">Lexer</a></td>
        </tr>

        <tr>
          <td>o <a class="toc" href="#Notifications">Notifications</a></td>

          <td>o <a class="toc" href="#GTK">GTK+</a></td>

          <td>o <a class="toc" href="#DeprecatedMessages">Deprecated messages</a></td>
        </tr>

        <tr>
          <td>o <a class="toc" href="#EditMessagesNeverSupportedByScintilla">Edit messages never
          supported by Scintilla</a></td>

          <td>o <a class="toc" href="#BuildingScintilla">Building Scintilla</a></td>
        </tr>
      </tbody>
    </table>

    <p>Messages with names of the form <code>SCI_SETxxxxx</code> often have a companion
    <code>SCI_GETxxxxx</code>. To save tedious repetition, if the <code>SCI_GETxxxxx</code> message
    returns the value set by the <code>SCI_SETxxxxx</code> message, the <code>SET</code> routine is
    described and the <code>GET</code> routine is left to your imagination.</p>

    <h2 id="TextRetrievalAndModification">Text retrieval and modification</h2>

    <p>Each character in a Scintilla document is followed by an associated byte of styling
    information. The combination of a character byte and a style byte is called a cell. Style bytes
    are interpreted as a style index in the low 5 bits and as 3 individual bits of <a class="jump"
    href="#Indicators">indicators</a>. This allows 32 fundamental styles, which is enough for most
    languages, and three independent indicators so that, for example, syntax errors, deprecated
    names and bad indentation could all be displayed at once. The number of bits used for styles
    can be altered with <a class="message"
    href="#SCI_SETSTYLEBITS"><code>SCI_SETSTYLEBITS</code></a> up to a maximum of 7 bits.
    The remaining bits can be used for indicators.</p>

    <p>Positions within the 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 document
    contains <code>nLen</code> characters, the last character is numbered <code>nLen</code>-1.
    The caret exists between character positions and can be located from before the first character (0)
    to after the last character (<code>nLen</code>).</p>

    <p>There are places where the caret can not go where two character bytes make up one character.
    This occurs when a DBCS character from a language like Japanese is included in the document or
    when line ends are marked with the CP/M standard of a carriage return followed by a line feed.
    The <code>INVALID_POSITION</code> constant (-1) represents an invalid position within the
    document.</p>

    <p>All lines of text in Scintilla are the same height, and this height is calculated from the
    largest font in any current style. This restriction is for performance; if lines differed in
    height then calculations involving positioning of text would require the text to be styled
    first.</p>
    <code><a class="message" href="#SCI_GETTEXT">SCI_GETTEXT(int length, char *text)</a><br />
     <a class="message" href="#SCI_SETTEXT">SCI_SETTEXT(&lt;unused&gt;, const char *text)</a><br />
     <a class="message" href="#SCI_SETSAVEPOINT">SCI_SETSAVEPOINT</a><br />
     <a class="message" href="#SCI_GETLINE">SCI_GETLINE(int line, char *text)</a><br />
     <a class="message" href="#SCI_REPLACESEL">SCI_REPLACESEL(&lt;unused&gt;, const char
    *text)</a><br />
     <a class="message" href="#SCI_SETREADONLY">SCI_SETREADONLY(bool readOnly)</a><br />
     <a class="message" href="#SCI_GETREADONLY">SCI_GETREADONLY</a><br />
     <a class="message" href="#SCI_GETTEXTRANGE">SCI_GETTEXTRANGE(&lt;unused&gt;, TextRange
    *tr)</a><br />
     <a class="message" href="#SCI_ALLOCATE">SCI_ALLOCATE(int bytes, &lt;unused&gt;)</a><br />
     <a class="message" href="#SCI_ADDTEXT">SCI_ADDTEXT(int length, const char *s)</a><br />
     <a class="message" href="#SCI_ADDSTYLEDTEXT">SCI_ADDSTYLEDTEXT(int length, cell *s)</a><br />
     <a class="message" href="#SCI_APPENDTEXT">SCI_APPENDTEXT(int length, const char *s)</a><br />
     <a class="message" href="#SCI_INSERTTEXT">SCI_INSERTTEXT(int pos, const char *text)</a><br />
     <a class="message" href="#SCI_CLEARALL">SCI_CLEARALL</a><br />
     <a class="message" href="#SCI_CLEARDOCUMENTSTYLE">SCI_CLEARDOCUMENTSTYLE</a><br />
     <a class="message" href="#SCI_GETCHARAT">SCI_GETCHARAT(int position)</a><br />
     <a class="message" href="#SCI_GETSTYLEAT">SCI_GETSTYLEAT(int position)</a><br />
     <a class="message" href="#SCI_GETSTYLEDTEXT">SCI_GETSTYLEDTEXT(&lt;unused&gt;, TextRange
    *tr)</a><br />
     <a class="message" href="#SCI_SETSTYLEBITS">SCI_SETSTYLEBITS(int bits)</a><br />
     <a class="message" href="#SCI_GETSTYLEBITS">SCI_GETSTYLEBITS</a><br />
     <a class="message" href="#SCI_TARGETASUTF8">SCI_TARGETASUTF8(&lt;unused&gt;, char *s)</a><br />
     <a class="message" href="#SCI_ENCODEDFROMUTF8">SCI_ENCODEDFROMUTF8(const char *utf8, char *encoded)</a><br />
     <a class="message" href="#SCI_SETLENGTHFORENCODE">SCI_SETLENGTHFORENCODE(int bytes)</a><br />
    </code>

    <p><b id="SCI_GETTEXT">SCI_GETTEXT(int length, char *text)</b><br />
     This returns <code>length</code>-1 characters of text from the start of the document plus one
    terminating 0 character. To collect all the text in a document, use <code>SCI_GETLENGTH</code>
    to get the number of characters in the document (<code>nLen</code>), allocate a character
    buffer of length <code>nLen+1</code> bytes, then call <code>SCI_GETTEXT(nLen+1, char
    *text)</code>. If the text argument is 0 then the length that should be allocated to store the
    entire document is returned.
    If you then save the text, you should use <code>SCI_SETSAVEPOINT</code> to mark
    the text as unmodified.</p>

    <p>See also: <code><a class="message" href="#SCI_GETSELTEXT">SCI_GETSELTEXT</a>, <a
    class="message" href="#SCI_GETCURLINE">SCI_GETCURLINE</a>, <a class="message"
    href="#SCI_GETLINE">SCI_GETLINE</a>, <a class="message"
    href="#SCI_GETSTYLEDTEXT">SCI_GETSTYLEDTEXT</a>, <a class="message"
    href="#SCI_GETTEXTRANGE">SCI_GETTEXTRANGE</a></code></p>

    <p><b id="SCI_SETTEXT">SCI_SETTEXT(&lt;unused&gt;, const char *text)</b><br />
     This replaces all the text in the document with the zero terminated text string you pass
    in.</p>

    <p><b id="SCI_SETSAVEPOINT">SCI_SETSAVEPOINT</b><br />
     This message tells Scintilla that the current state of the document is unmodified. This is
    usually done when the file is saved or loaded, hence the name "save point". As Scintilla
    performs undo and redo operations, it notifies the container that it has entered or left the
    save point with <code><a class="message"
    href="#SCN_SAVEPOINTREACHED">SCN_SAVEPOINTREACHED</a></code> and <code><a class="message"
    href="#SCN_SAVEPOINTLEFT">SCN_SAVEPOINTLEFT</a></code> <a class="jump"
    href="#Notifications">notification messages</a>, allowing the container to know if the file
    should be considered dirty or not.</p>

    <p>See also: <code><a class="message" href="#SCI_EMPTYUNDOBUFFER">SCI_EMPTYUNDOBUFFER</a>, <a
    class="message" href="#SCI_GETMODIFY">SCI_GETMODIFY</a></code></p>

    <p><b id="SCI_GETLINE">SCI_GETLINE(int line, char *text)</b><br />
     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 to you to make sure that the buffer
    is long enough for the text, use <a class="message"
    href="#SCI_LINELENGTH"><code>SCI_LINELENGTH(int line)</code></a>. The returned value is the
    number of characters copied to the buffer. The returned text includes any end of line
    characters. If you ask for a line number outside the range of lines in the document, 0
    characters are copied. If the text argument is 0 then the length that should be allocated
    to store the entire line is returned.</p>

    <p>See also: <code><a class="message" href="#SCI_GETCURLINE">SCI_GETCURLINE</a>, <a
    class="message" href="#SCI_GETSELTEXT">SCI_GETSELTEXT</a>, <a class="message"
    href="#SCI_GETTEXTRANGE">SCI_GETTEXTRANGE</a>, <a class="message"
    href="#SCI_GETSTYLEDTEXT">SCI_GETSTYLEDTEXT</a>, <a class="message"
    href="#SCI_GETTEXT">SCI_GETTEXT</a></code></p>

    <p><b id="SCI_REPLACESEL">SCI_REPLACESEL(&lt;unused&gt;, const char *text)</b><br />
     The currently selected text between the <a class="jump" href="#SelectionAndInformation">anchor
    and the current position</a> is replaced by the 0 terminated text string. If the anchor and
    current position are the same, the text is inserted at the caret position. The caret is
    positioned after the inserted text and the caret is scrolled into view.</p>

    <p><b id="SCI_SETREADONLY">SCI_SETREADONLY(bool readOnly)</b><br />
     <b id="SCI_GETREADONLY">SCI_GETREADONLY</b><br />
     These messages set and get the read-only flag for the document. If you mark a document as read
    only, attempts to modify the text cause the <a class="message"
    href="#SCN_MODIFYATTEMPTRO"><code>SCN_MODIFYATTEMPTRO</code></a> notification.</p>

    <p><b id="SCI_GETTEXTRANGE">SCI_GETTEXTRANGE(&lt;unused&gt;, <a class="jump"
    href="#TextRange">TextRange</a> *tr)</b><br />
     This collects the text between the positions <code>cpMin</code> and <code>cpMax</code> and
    copies it to <code>lpstrText</code> (see <code>struct TextRange</code> in
    <code>Scintilla.h</code>). If <code>cpMax</code> is -1, text is returned to the end of the
    document. The text is 0 terminated, so you must supply a buffer that is at least 1 character
    longer than the number of characters you wish to read. The return value is the length of the
    returned text not including the terminating 0.</p>

    <p>See also: <code><a class="message" href="#SCI_GETSELTEXT">SCI_GETSELTEXT</a>, <a
    class="message" href="#SCI_GETLINE">SCI_GETLINE</a>, <a class="message"
    href="#SCI_GETCURLINE">SCI_GETCURLINE</a>, <a class="message"
    href="#SCI_GETSTYLEDTEXT">SCI_GETSTYLEDTEXT</a>, <a class="message"
    href="#SCI_GETTEXT">SCI_GETTEXT</a></code></p>

    <p><b id="SCI_GETSTYLEDTEXT">SCI_GETSTYLEDTEXT(&lt;unused&gt;, <a class="jump"
    href="#TextRange">TextRange</a> *tr)</b><br />
     This collects styled text into a buffer using two bytes for each cell, with the character at
    the lower address of each pair and the style byte at the upper address. Characters between the
    positions <code>cpMin</code> and <code>cpMax</code> are copied to <code>lpstrText</code> (see
    <code>struct TextRange</code> in <code>Scintilla.h</code>). Two 0 bytes are added to the end of
    the text, so the buffer that <code>lpstrText</code> points at must be at least
    <code>2*(cpMax-cpMin)+2</code> bytes long. No check is made for sensible values of
    <code>cpMin</code> or <code>cpMax</code>. Positions outside the document return character codes
    and style bytes of 0.</p>

    <p>See also: <code><a class="message" href="#SCI_GETSELTEXT">SCI_GETSELTEXT</a>, <a
    class="message" href="#SCI_GETLINE">SCI_GETLINE</a>, <a class="message"
    href="#SCI_GETCURLINE">SCI_GETCURLINE</a>, <a class="message"
    href="#SCI_GETTEXTRANGE">SCI_GETTEXTRANGE</a>, <a class="message"
    href="#SCI_GETTEXT">SCI_GETTEXT</a></code></p>

    <p><b id="SCI_ALLOCATE">SCI_ALLOCATE(int bytes, &lt;unused&gt;)</b><br />
     Allocate a document buffer large enough to store a given number of bytes.
     The document will not be made smaller than its current contents.</p>

    <p><b id="SCI_ADDTEXT">SCI_ADDTEXT(int length, const char *s)</b><br />
     This inserts the first <code>length</code> characters from the string <code>s</code>
    at the current position. This will include any 0's in the string that you might have expected
    to stop the insert operation. The current position is set at the end of the inserted text,
    but it is not scrolled into view.</p>

    <p><b id="SCI_ADDSTYLEDTEXT">SCI_ADDSTYLEDTEXT(int length, cell *s)</b><br />
     This behaves just like <code>SCI_ADDTEXT</code>, but inserts styled text.</p>

    <p><b id="SCI_APPENDTEXT">SCI_APPENDTEXT(int length, const char *s)</b><br />
     This adds the first <code>length</code> characters from the string <code>s</code> to the end
    of the document. This will include any 0's in the string that you might have expected to stop
    the operation. The current selection is not changed and the new text is not scrolled into
    view.</p>

    <p><b id="SCI_INSERTTEXT">SCI_INSERTTEXT(int pos, const char *text)</b><br />
     This inserts the zero terminated <code>text</code> string at position <code>pos</code> or at
    the current position if <code>pos</code> is -1. If the current position is after the insertion point
    then it is moved along with its surrounding text but no scrolling is performed.</p>

    <p><b id="SCI_CLEARALL">SCI_CLEARALL</b><br />
     Unless the document is read-only, this deletes all the text.</p>

    <p><b id="SCI_CLEARDOCUMENTSTYLE">SCI_CLEARDOCUMENTSTYLE</b><br />
     When wanting to completely restyle the document, for example after choosing a lexer, the
    <code>SCI_CLEARDOCUMENTSTYLE</code> can be used to clear all styling information and reset the
    folding state.</p>

    <p><b id="SCI_GETCHARAT">SCI_GETCHARAT(int pos)</b><br />
     This returns the character at <code>pos</code> in the document or 0 if <code>pos</code> is
    negative or past the end of the document.</p>

    <p><b id="SCI_GETSTYLEAT">SCI_GETSTYLEAT(int pos)</b><br />
     This returns the style at <code>pos</code> in the document, or 0 if <code>pos</code> is
    negative or past the end of the document.</p>

    <p><b id="SCI_SETSTYLEBITS">SCI_SETSTYLEBITS(int bits)</b><br />
     <b id="SCI_GETSTYLEBITS">SCI_GETSTYLEBITS</b><br />
     This pair of routines sets and reads back the number of bits in each cell to use for styling,
    to a maximum of 7 style bits. The remaining bits can be used as indicators. The standard
    setting is <code>SCI_SETSTYLEBITS(5)</code>.
    The number of styling bits needed by the current lexer can be found with
    <a class="message" href="#SCI_GETSTYLEBITSNEEDED">SCI_GETSTYLEBITSNEEDED</a>.</p>

    <p><b id="TextRange">TextRange</b> and <b id="CharacterRange">CharacterRange</b><br />
     These structures are defined to be exactly the same shape as the Win32 <code>TEXTRANGE</code>
    and <code>CHARRANGE</code>, so that older code that treats Scintilla as a RichEdit will
    work.</p>