diff options
Diffstat (limited to 'doc/ScintillaDoc.html')
| -rw-r--r-- | doc/ScintillaDoc.html | 139 |
1 files changed, 46 insertions, 93 deletions
diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index 5350e8537..e0880b071 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -364,20 +364,9 @@ <h2 id="TextRetrievalAndModification">Text retrieval and modification</h2> - <p>Each byte in a Scintilla document is followed by an associated byte of styling + <p>Each byte in a Scintilla document is associated with a byte of styling information. The combination of a character byte and a style byte is called a cell. Style bytes - are interpreted an index into an array of styles. - Style bytes may be split into an index and a set of indicator bits - but this use is discouraged and indicators should now use - <a class="message" href ="#SCI_INDICATORFILLRANGE">SCI_INDICATORFILLRANGE</a> - and related calls. - The default split is with the index in the low 5 bits and 3 high bits as <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 8 bits. - The remaining bits can be used for indicators.</p> + are interpreted an index into an array of styles.</p> <p>In this document, 'character' normally refers to a byte even when multi-byte characters are used. Lengths measure the numbers of bytes, not the amount of characters in those bytes.</p> @@ -421,8 +410,6 @@ <a class="message" href="#SCI_GETSTYLEAT">SCI_GETSTYLEAT(int position)</a><br /> <a class="message" href="#SCI_GETSTYLEDTEXT">SCI_GETSTYLEDTEXT(<unused>, Sci_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_RELEASEALLEXTENDEDSTYLES">SCI_RELEASEALLEXTENDEDSTYLES</a><br /> <a class="message" href="#SCI_ALLOCATEEXTENDEDSTYLES">SCI_ALLOCATEEXTENDEDSTYLES(int numberStyles)</a><br /> <a class="message" href="#SCI_TARGETASUTF8">SCI_TARGETASUTF8(<unused>, char *s)</a><br /> @@ -570,14 +557,6 @@ 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 8 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="SCI_RELEASEALLEXTENDEDSTYLES">SCI_RELEASEALLEXTENDEDSTYLES</b><br /> <b id="SCI_ALLOCATEEXTENDEDSTYLES">SCI_ALLOCATEEXTENDEDSTYLES(int numberStyles)</b><br /> Extended styles are used for features like textual margins and annotations as well as internally by Scintilla. @@ -2329,12 +2308,7 @@ struct Sci_TextToFind { <h2 id="Styling">Styling</h2> - <p>The styling messages allow you to assign styles to text. The standard Scintilla settings - divide the 8 style bits available for each character into 5 bits (0 to 4 = <a class="jump" - href="#StyleDefinition">styles 0 to 31</a>) that set a style and three bits (5 to 7) that - define <a class="jump" href="#Indicators">indicators</a>. You can change the balance between - styles and indicators with <a class="message" - href="#SCI_SETSTYLEBITS"><code>SCI_SETSTYLEBITS</code></a>. If your styling needs can be met by + <p>The styling messages allow you to assign styles to text. If your styling needs can be met by one of the standard lexers, or if you can write your own, then a lexer is probably the easiest way to style your document. If you choose to use the container to do the styling you can use the <a class="message" href="#SCI_SETLEXER"><code>SCI_SETLEXER</code></a> command to select @@ -2345,7 +2319,7 @@ struct Sci_TextToFind { use the styling commands to mark errors detected by a compiler. The following commands can be used.</p> <code><a class="message" href="#SCI_GETENDSTYLED">SCI_GETENDSTYLED</a><br /> - <a class="message" href="#SCI_STARTSTYLING">SCI_STARTSTYLING(int position, int mask)</a><br /> + <a class="message" href="#SCI_STARTSTYLING">SCI_STARTSTYLING(int position, int unused)</a><br /> <a class="message" href="#SCI_SETSTYLING">SCI_SETSTYLING(int length, int style)</a><br /> <a class="message" href="#SCI_SETSTYLINGEX">SCI_SETSTYLINGEX(int length, const char *styles)</a><br /> @@ -2363,31 +2337,23 @@ struct Sci_TextToFind { container. The container can send <code>SCI_GETENDSTYLED</code> to work out where it needs to start styling. Scintilla will always ask to style whole lines.</p> - <p><b id="SCI_STARTSTYLING">SCI_STARTSTYLING(int pos, int mask)</b><br /> - This prepares for styling by setting the styling position <code>pos</code> to start at and a - <code>mask</code> indicating which bits of the style bytes can be set. The mask allows styling - to occur over several passes, with, for example, basic styling done on an initial pass to - ensure that the text of the code is seen quickly and correctly, and then a second slower pass, - detecting syntax errors and using indicators to show where these are. For example, with the - standard settings of 5 style bits and 3 indicator bits, you would use a <code>mask</code> value - of 31 (0x1f) if you were setting text styles and did not want to change the indicators. After + <p><b id="SCI_STARTSTYLING">SCI_STARTSTYLING(int pos, int unused)</b><br /> + This prepares for styling by setting the styling position <code>pos</code> to start at. + The unused argument was used in earlier versions but is now ignored. + After <code>SCI_STARTSTYLING</code>, send multiple <code>SCI_SETSTYLING</code> messages for each lexical entity to style.</p> <p><b id="SCI_SETSTYLING">SCI_SETSTYLING(int length, int style)</b><br /> This message sets the style of <code>length</code> characters starting at the styling position - and then increases the styling position by <code>length</code>, ready for the next call. If - <code>sCell</code> is the style byte, the operation is:<br /> - <code>if ((sCell & mask) != style) sCell = (sCell & ~mask) | (style & - mask);</code><br /> + and then increases the styling position by <code>length</code>, ready for the next call.<br /> </p> <p><b id="SCI_SETSTYLINGEX">SCI_SETSTYLINGEX(int length, const char *styles)</b><br /> As an alternative to <code>SCI_SETSTYLING</code>, which applies the same style to each byte, you can use this message which specifies the styles for each of <code>length</code> bytes from the styling position and then increases the styling position by <code>length</code>, ready for - the next call. The <code>length</code> styling bytes pointed at by <code>styles</code> should - not contain any bits not set in mask.</p> + the next call.</p> <p><b id="SCI_SETLINESTATE">SCI_SETLINESTATE(int line, int value)</b><br /> <b id="SCI_GETLINESTATE">SCI_GETLINESTATE(int line)</b><br /> @@ -2405,9 +2371,8 @@ struct Sci_TextToFind { <p>While the style setting messages mentioned above change the style numbers associated with text, these messages define how those style numbers are interpreted visually. There are 256 - lexer styles that can be set, numbered 0 to <code>STYLE_MAX</code> (255). Unless you use <a - class="message" href="#SCI_SETSTYLEBITS"><code>SCI_SETSTYLEBITS</code></a> to change the number - of style bits, styles 0 to 31 are used to set the text attributes. There are also some + lexer styles that can be set, numbered 0 to <code>STYLE_MAX</code> (255). + There are also some predefined numbered styles starting at 32, The following <code>STYLE_</code>* constants are defined.</p> @@ -2504,9 +2469,7 @@ struct Sci_TextToFind { <td>255</td> <td>This is not a style but is the number of the maximum style that can be set. Styles - between <code>STYLE_LASTPREDEFINED</code> and <code>STYLE_MAX</code> would be appropriate - if you used <a class="message" href="#SCI_SETSTYLEBITS"><code>SCI_SETSTYLEBITS</code></a> - to set more than 5 style bits.</td> + between <code>STYLE_LASTPREDEFINED</code> and <code>STYLE_MAX</code> may be used.</td> </tr> </tbody> </table> @@ -3196,9 +3159,6 @@ struct Sci_TextToFind { </p> <h2 id="OtherSettings">Other settings</h2> - <code><a class="message" href="#SCI_SETUSEPALETTE">SCI_SETUSEPALETTE(bool - allowPaletteUse)</a><br /> - <a class="message" href="#SCI_GETUSEPALETTE">SCI_GETUSEPALETTE</a><br /> <a class="message" href="#SCI_SETBUFFEREDDRAW">SCI_SETBUFFEREDDRAW(bool isBuffered)</a><br /> <a class="message" href="#SCI_GETBUFFEREDDRAW">SCI_GETBUFFEREDDRAW</a><br /> <a class="message" href="#SCI_SETTWOPHASEDRAW">SCI_SETTWOPHASEDRAW(bool twoPhase)</a><br /> @@ -3839,10 +3799,7 @@ struct Sci_TextToFind { <p>Indicators are used to display additional information over the top of styling. They can be used to show, for example, syntax errors, deprecated names and bad indentation - by drawing underlines under text or boxes around text. Originally, Scintilla stored indicator information in - the style bytes but this has proved limiting, so now up to 32 separately stored indicators may be used. - While style byte indicators currently still work, they will soon be removed so all the bits in each style - byte can be used for lexical states.</p> + by drawing underlines under text or boxes around text.</p> <p>Indicators may be displayed as simple underlines, squiggly underlines, a line of small 'T' shapes, a line of diagonal hatching, a strike-out or a rectangle around the text.</p> @@ -3853,6 +3810,12 @@ struct Sci_TextToFind { by lexers (0..7) and a range for use by containers (8=<code>INDIC_CONTAINER</code> .. 31=<code>INDIC_MAX</code>).</p> + <p>Originally, Scintilla used a different technique for indicators but this + has been <a href="#RemovedFeatures">removed</a> + and the APIs perform <a href="#StyleByteIndicators">no action</a>. + While both techniques were supported, the term "modern indicators" was used for the + newer implementation.</p> + <code><a class="message" href="#SCI_INDICSETSTYLE">SCI_INDICSETSTYLE(int indicatorNumber, int indicatorStyle)</a><br /> <a class="message" href="#SCI_INDICGETSTYLE">SCI_INDICGETSTYLE(int indicatorNumber)</a><br /> @@ -4074,12 +4037,10 @@ struct Sci_TextToFind { <p><b id="SCI_INDICSETUNDER">SCI_INDICSETUNDER(int indicatorNumber, bool under)</b><br /> <b id="SCI_INDICGETUNDER">SCI_INDICGETUNDER(int indicatorNumber)</b><br /> These two messages set and get whether an indicator is drawn under text or over(default). - Drawing under text works only for modern indicators when <a class="message" href="#SCI_SETTWOPHASEDRAW">two phase drawing</a> + Drawing under text works only for indicators when <a class="message" href="#SCI_SETTWOPHASEDRAW">two phase drawing</a> is enabled.</p> - <h3 id="ModernIndicators">Modern Indicators</h3> - - <p>Modern indicators are stored in a format similar to run length encoding which is efficient in both + <p>Indicators are stored in a format similar to run length encoding which is efficient in both speed and storage for sparse information.</p> <p>An indicator may store different values for each range but currently all values are drawn the same. In the future, it may be possible to draw different values in different styles.</p> @@ -4146,32 +4107,8 @@ struct Sci_TextToFind { This message hides the find indicator. </p> - <h3 id="StyleByteIndicators">Style Byte Indicators (deprecated)</h3> - <p>By default, Scintilla organizes the style byte associated with each text byte as 5 bits of - style information (for 32 styles) and 3 bits of indicator information for 3 independent - indicators so that, for example, syntax errors, deprecated names and bad indentation could all - be displayed at once.</p> - - <p>The indicators are set using <a class="message" - href="#SCI_STARTSTYLING"><code>SCI_STARTSTYLING</code></a> with a <code>INDICS_MASK</code> mask - and <a class="message" href="#SCI_SETSTYLING"><code>SCI_SETSTYLING</code></a> with the values - <code>INDIC0_MASK</code>, <code>INDIC1_MASK</code> and <code>INDIC2_MASK</code>.</p> - - <p>If you are using indicators in a buffer that has a lexer active - (see <a class="message" href="#SCI_SETLEXER"><code>SCI_SETLEXER</code></a>), - you must save lexing state information before setting any indicators and restore it afterwards. - Use <a class="message" href="#SCI_GETENDSTYLED"><code>SCI_GETENDSTYLED</code></a> - to retrieve the current "styled to" position and - <a class="message" href="#SCI_STARTSTYLING"><code>SCI_STARTSTYLING</code></a> - to reset the styling position and mask (<code>0x1f </code> in the default layout of 5 style bits and 3 indicator bits) - when you are done.</p> - - <p>The number of bits used for styles can be altered with <a class="message" - href="#SCI_SETSTYLEBITS"><code>SCI_SETSTYLEBITS</code></a> from 0 to 8 bits. The remaining bits - can be used for indicators, so there can be from 1 to 8 indicators. However, the - <code>INDIC*_MASK</code> constants defined in <code>Scintilla.h</code> all assume 5 bits of - styling information and 3 indicators. If you use a different arrangement, you must define your - own constants.</p> + <p>Earlier versions of Scintilla allowed <a href="#StyleByteIndicators">partitioning style bytes</a> + between style numbers and indicators and provided APIs for setting and querying this.</p> <h2 id="Autocompletion">Autocompletion</h2> @@ -5968,7 +5905,6 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ <a class="message" href="#SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions)</a><br /> <a class="message" href="#SCI_SETKEYWORDS">SCI_SETKEYWORDS(int keyWordSet, const char *keyWordList)</a><br /> - <a class="message" href="#SCI_GETSTYLEBITSNEEDED">SCI_GETSTYLEBITSNEEDED</a><br /> <a class="message" href="#SCI_GETSUBSTYLEBASES">SCI_GETSUBSTYLEBASES(<unused>, char *styles)</a><br /> <a class="message" href="#SCI_DISTANCETOSECONDARYSTYLES">SCI_DISTANCETOSECONDARYSTYLES</a><br /> @@ -6118,11 +6054,6 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ <p><b id="SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions)</b><br /> A description of all of the keyword sets separated by "\n" is returned by <code>SCI_DESCRIBEKEYWORDSETS</code>.</p> - <p><b id="SCI_GETSTYLEBITSNEEDED">SCI_GETSTYLEBITSNEEDED</b><br /> - Retrieve the number of bits the current lexer needs for styling. This should normally be the argument - to <a class="message" href="#SCI_SETSTYLEBITS">SCI_SETSTYLEBITS</a>. - </p> - <h3 id="Substyles">Substyles</h3> <p>Lexers may support several different sublanguages and each sublanguage may want to style some number of sets of identifiers (or similar lexemes such as documentation keywords) uniquely. Preallocating a large number for each @@ -6441,6 +6372,8 @@ segments then changing the statement <code>#define BEOS 0</code> to <code>#defin document. The lexer can call <code>ChangeLexerState</code> to signal to the document that it should relex and display more.</p> +<p>For <code>StartStyling</code> the mask argument has no effect. It was used in version 3.4.2 and earlier.</p> + <p><code>SetErrorStatus</code> 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 @@ -7481,6 +7414,20 @@ EM_FORMATRANGE <b id="SCI_GETUSEPALETTE">SCI_GETUSEPALETTE</b> Deprecated<br /> Scintilla no longer supports palette mode. The last version to support palettes was 2.29. Any calls to these methods should be removed.</p> + + <p>The following are features that should be removed from calling code but are still + defined to avoid breaking callers.</p> + + <p id="StyleByteIndicators"><b id="SCI_SETSTYLEBITS">SCI_SETSTYLEBITS(int bits)</b> Deprecated<br /> + <b id="SCI_GETSTYLEBITS">SCI_GETSTYLEBITS</b> Deprecated<br /> + <b id="SCI_GETSTYLEBITSNEEDED">SCI_GETSTYLEBITSNEEDED</b> Deprecated<br /> + <code>INDIC0_MASK</code>, <code>INDIC1_MASK</code>, <code>INDIC2_MASK</code>, <code>INDICS_MASK</code> Deprecated<br /> + Scintilla no longer supports style byte indicators. The last version to support style byte indicators was 3.4.2. + Any use of these symbols should be removed and replaced with <a href="#Indicators">standard indicators</a>. + <code>SCI_GETSTYLEBITS</code> and <code>SCI_GETSTYLEBITSNEEDED</code> always return 8, + indicating that 8 bits are used for styling and there are 256 styles.</p> + </p> + <h2 id="EditMessagesNeverSupportedByScintilla">Edit messages never supported by Scintilla</h2> <pre> @@ -7517,6 +7464,12 @@ EM_SETTARGETDEVICE that makes sense. As it is not intended for use in a word processor, some edit messages can not be sensibly handled. Unsupported messages have no effect.</p> + <h2 id="RemovedFeatures">Removed features</h2> + + <p>Previous versions of Scintilla allowed indicators to be stord in bits of each style byte. + This was deprecated in 2007 and removed in 2014 with release 3.4.3. + All uses of style byte indicators should be replaced with <a href="#Indicators">standard indicators</a>.</p> + <h2 id="BuildingScintilla">Building Scintilla</h2> <p>To build Scintilla or SciTE, see the README file present in both the Scintilla and SciTE |