From 0e3fdb608dffecddfac735f5ab7a836c89380659 Mon Sep 17 00:00:00 2001 From: nyamatongwe Date: Mon, 23 Apr 2007 01:58:05 +0000 Subject: Updated indicator documentation to deprecate style byte indicators in favour of modern indicators. --- doc/ScintillaDoc.html | 88 ++++++++++++++++++++++++++++----------------------- 1 file 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 @@

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 SCI_INDICATORFILLRANGE + and related calls. + The default split is with the index in the low 5 bits and 3 high bits as indicators. 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 {

Indicators

-

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.

- -

The indicators are set using SCI_STARTSTYLING with a INDICS_MASK mask - and SCI_SETSTYLING with the values - INDIC0_MASK, INDIC1_MASK and INDIC2_MASK.

- -

If you are using indicators in a buffer that has a lexer active - (see SCI_SETLEXER), - you must save lexing state information before setting any indicators and restore it afterwards. - Use SCI_GETENDSTYLED - to retrieve the current "styled to" position and - SCI_STARTSTYLING - to reset the styling position and mask (0x1f in the default layout of 5 style bits and 3 indicator bits) - when you are done.

+

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.

-

The number of bits used for styles can be altered with SCI_SETSTYLEBITS from 0 to 7 bits. The remaining bits - can be used for indicators, so there can be from 1 to 8 indicators. However, the - INDIC*_MASK constants defined in Scintilla.h all assume 5 bits of - styling information and 3 indicators. If you use a different arrangement, you must define your - own constants.

+

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.

The SCI_INDIC* messages allow you to get and set the visual appearance of the - indicators. They all use an indicatorNumber 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.

+ indicators. They all use an indicatorNumber 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=INDIC_CONTAINER .. 31=INDIC_MAX).

+ SCI_INDICSETSTYLE(int indicatorNumber, int indicatorStyle)
SCI_INDICGETSTYLE(int indicatorNumber)
@@ -3046,16 +3036,9 @@ struct TextToFind { SCI_INDICSETFORE(1, 0xff0000); (light blue)
SCI_INDICSETFORE(2, 0x0000ff); (light red)

-

Extended Indicators

-

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.

-

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 +

Modern Indicators

+ +

Modern indicators are stored in a format similar to run length encoding which is efficient in both speed and storage for sparse information.

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.

@@ -3099,6 +3082,33 @@ struct TextToFind { Can be used to iterate through the document to discover all the indicator positions.

+

Style Byte Indicators (deprecated)

+

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.

+ +

The indicators are set using SCI_STARTSTYLING with a INDICS_MASK mask + and SCI_SETSTYLING with the values + INDIC0_MASK, INDIC1_MASK and INDIC2_MASK.

+ +

If you are using indicators in a buffer that has a lexer active + (see SCI_SETLEXER), + you must save lexing state information before setting any indicators and restore it afterwards. + Use SCI_GETENDSTYLED + to retrieve the current "styled to" position and + SCI_STARTSTYLING + to reset the styling position and mask (0x1f in the default layout of 5 style bits and 3 indicator bits) + when you are done.

+ +

The number of bits used for styles can be altered with SCI_SETSTYLEBITS from 0 to 7 bits. The remaining bits + can be used for indicators, so there can be from 1 to 8 indicators. However, the + INDIC*_MASK constants defined in Scintilla.h all assume 5 bits of + styling information and 3 indicators. If you use a different arrangement, you must define your + own constants.

+

Autocompletion

-- cgit v1.2.3