diff options
| -rw-r--r-- | doc/ScintillaDoc.html | 88 |
1 files changed, 49 insertions, 39 deletions
diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index fbd77f29f..5f550aa72 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -279,7 +279,12 @@ <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" + 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 sould 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 @@ -2908,37 +2913,22 @@ struct TextToFind { <h2 id="Indicators">Indicators</h2> - <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. 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> - - <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>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> - <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 7 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>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> <p>The <code>SCI_INDIC*</code> messages allow you to get and set the visual appearance of the - indicators. They all use an <code>indicatorNumber</code> argument in the range 0 to 7 to set - the indicator to style. With the default settings, only indicators 0, 1 and 2 will have any - visible effect.</p> + indicators. They all use an <code>indicatorNumber</code> argument in the range 0 to INDIC_MAX(31) + to set the indicator to style. To prevent interference the set of indicators is divided up into a range for use + by lexers (0..7) and a range for use by containers + (8=<code>INDIC_CONTAINER</code> .. 31=<code>INDIC_MAX</code>).</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 /> @@ -3046,16 +3036,9 @@ struct TextToFind { <code>SCI_INDICSETFORE(1, 0xff0000);</code> (light blue)<br /> <code>SCI_INDICSETFORE(2, 0x0000ff);</code> (light red)</p> - <h2 id="Extended Indicators">Extended Indicators</h2> - <p>Incorporating indicators within style bytes has proved limiting so Scintilla is changing to store - indicators separately from style bytes. The following APIs should be used for new code and existing - code should be updated to use these APIs rather than style bytes. After the transition is complete, - indicators within style bytes will be removed so that all the bits in each style byte can be used for - lexical states.</p> - <p>Up to 32 indicators may be used. Lexers should use indicators 3 to 7 and containers - 8 to 31 to ensure they do not conflict. Indicators 0, 1, and 2 are the existing style byte indicators and should - be avoided in the transition period. - Extended indicators are stored in a format similar to run length encoding which is efficient in both + <h3 id="Modern Indicators">Modern Indicators</h3> + + <p>Modern 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> @@ -3099,6 +3082,33 @@ struct TextToFind { Can be used to iterate through the document to discover all the indicator positions. </p> + <h3 id="Style Byte Indicators">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 7 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> + <h2 id="Autocompletion">Autocompletion</h2> |