From 8497317864816c0f7a4b5baf3229c7a3336f55d8 Mon Sep 17 00:00:00 2001 From: Neil Date: Mon, 10 May 2021 17:40:27 +1000 Subject: Change the way that selections and carets are drawn to use the element APIs. --- doc/ScintillaDoc.html | 270 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 226 insertions(+), 44 deletions(-) (limited to 'doc/ScintillaDoc.html') diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index 41cac0d2b..7e120c44c 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -51,7 +51,9 @@ table.standard td { padding: 1px 5px 1px 5px; } - + tr.section { + border-top:1px solid #808080; + } .S0 { color: #808080; } @@ -99,6 +101,12 @@ .deprecated { text-decoration: line-through red; } + A.discouraged { + text-decoration: line-through #FFB000; + } + .discouraged { + text-decoration: line-through #FFB000; + } .parameter { font-style:italic; } @@ -364,7 +372,7 @@ - ○ Caret, selection, and hotspot styles + ○ Selection, caret, and hotspot styles ○ Character representations @@ -1713,12 +1721,15 @@ struct Sci_TextToFind { SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE → position

- SCI_SETADDITIONALSELALPHA(alpha alpha)
- SCI_GETADDITIONALSELALPHA → int
- SCI_SETADDITIONALSELFORE(colour fore)
- SCI_SETADDITIONALSELBACK(colour back)
- SCI_SETADDITIONALCARETFORE(colour fore)
- SCI_GETADDITIONALCARETFORE → colour
+ SC_ELEMENT_SELECTION_ADDITIONAL_TEXT : colouralpha
+ SC_ELEMENT_SELECTION_ADDITIONAL_BACK : colouralpha
+ SCI_SETADDITIONALSELALPHA(alpha alpha)
+ SCI_GETADDITIONALSELALPHA → int
+ SCI_SETADDITIONALSELFORE(colour fore)
+ SCI_SETADDITIONALSELBACK(colour back)
+ SC_ELEMENT_CARET_ADDITIONAL : colouralpha
+ SCI_SETADDITIONALCARETFORE(colour fore)
+ SCI_GETADDITIONALCARETFORE → colour
SCI_SETADDITIONALCARETSBLINK(bool additionalCaretsBlink)
SCI_GETADDITIONALCARETSBLINK → bool
SCI_SETADDITIONALCARETSVISIBLE(bool additionalCaretsVisible)
@@ -1871,15 +1882,22 @@ struct Sci_TextToFind { After setting the rectangular selection, this is broken down into multiple selections, one for each line.

+ SC_ELEMENT_SELECTION_ADDITIONAL_TEXT : colouralpha
+ SC_ELEMENT_SELECTION_ADDITIONAL_BACK : colouralpha
SCI_SETADDITIONALSELALPHA(alpha alpha)
SCI_GETADDITIONALSELALPHA → int
SCI_SETADDITIONALSELFORE(colour fore)
SCI_SETADDITIONALSELBACK(colour back)
Modify the appearance of additional selections so that they can be differentiated from the main selection which has its appearance set with + SC_ELEMENT_SELECTION_TEXT, + SC_ELEMENT_SELECTION_BACK, SCI_SETSELALPHA, SCI_GETSELALPHA, SCI_SETSELFORE, and SCI_SETSELBACK. + The element APIs are preferred and the following messages discouraged. + The additional selection background is drawn on the layer defined for all selection backgrounds by + SCI_SETSELECTIONLAYER. SCI_SETADDITIONALSELFORE and SCI_SETADDITIONALSELBACK calls have no effect until SCI_SETSELFORE @@ -1888,12 +1906,15 @@ struct Sci_TextToFind { SCI_SETSELFORE, and SCI_SETSELBACK will overwrite the values set by SCI_SETADDITIONALSEL* functions.

+

+ SC_ELEMENT_CARET_ADDITIONAL : colouralpha
SCI_SETADDITIONALCARETFORE(colour fore)
SCI_GETADDITIONALCARETFORE → colour
SCI_SETADDITIONALCARETSBLINK(bool additionalCaretsBlink)
SCI_GETADDITIONALCARETSBLINK → bool
Modify the appearance of additional carets so that they can be differentiated from the main caret which has its appearance set with + SC_ELEMENT_CARET, SCI_SETCARETFORE, SCI_GETCARETFORE, SCI_SETCARETPERIOD, and @@ -2451,7 +2472,7 @@ struct Sci_TextToFind { SCI_GETMOUSEWHEELCAPTURES → bool
On Windows, Scintilla captures all WM_MOUSEWHEEL messages if it has the focus, even if the mouse pointer is nowhere near the Scintilla editor window. This - behavior can be changed with SCI_SETMOUSEWHEELCAPTURES(0) so that + behaviour can be changed with SCI_SETMOUSEWHEELCAPTURES(0) so that Scintilla passes the WM_MOUSEWHEEL messages to its parent window. Scintilla will still react to the mouse wheel if the mouse pointer is over the editor window.

@@ -3269,7 +3290,7 @@ struct Sci_TextToFind { - + SC_ELEMENT_LIST 0 Opaque @@ -3297,6 +3318,83 @@ struct Sci_TextToFind { Win32 Background colour of selected item in autocompletion lists + + SC_ELEMENT_SELECTION_TEXT + 10 + Translucent + All + Text colour of main selection + + + SC_ELEMENT_SELECTION_BACK + 11 + Translucent + All + Background colour of main selection + + + SC_ELEMENT_SELECTION_ADDITIONAL_TEXT + 12 + Translucent + All + Text colour of additional selections + + + SC_ELEMENT_SELECTION_ADDITIONAL_BACK + 13 + Translucent + All + Background colour of additional selections + + + SC_ELEMENT_SELECTION_SECONDARY_TEXT + 14 + Translucent + All + Text colour of selections when another window contains the primary selection + + + SC_ELEMENT_SELECTION_SECONDARY_BACK + 15 + Translucent + All + Background colour of selections when another window contains the primary selection + + + SC_ELEMENT_SELECTION_NO_FOCUS_TEXT + 16 + Translucent + All + Text colour of selections when another window has focus + + + SC_ELEMENT_SELECTION_NO_FOCUS_BACK + 17 + Translucent + All + Background colour of selections when another window has focus + + + SC_ELEMENT_CARET + 40 + Translucent + All + Colour of caret for main selection + + + SC_ELEMENT_CARET_ADDITIONAL + 41 + Translucent + All + Colour of caret for additional selections + + + SC_ELEMENT_CARET_SECONDARY + 42 + Translucent + All + Colour of carets when another window has focus + @@ -3309,22 +3407,40 @@ struct Sci_TextToFind { The default value is US English "en-us".

-

Caret, selection, and hotspot styles

+

Selection, caret, and hotspot styles

-

The selection is shown by changing the foreground and/or background colours. If one of these - is not set then that attribute is not changed for the selection. The default is to show the - selection by changing the background to light grey and leaving the foreground the same as when +

The selection is shown by changing the text and/or background colours. + If the selected text colour is not set then that attribute is not changed for the selection. + The default is to show the + selection by changing the background and leaving the foreground the same as when it was not selected. When there is no selection, the current insertion point is marked by the text caret. This is a vertical line that is normally blinking on and off to attract the users attention.

- SCI_SETSELFORE(bool useSetting, colour fore)
- SCI_SETSELBACK(bool useSetting, colour back)
- SCI_SETSELALPHA(alpha alpha)
- SCI_GETSELALPHA → int
+

On most platforms, a default grey selection background is used but, on macOS, the system-defined + selection background is used. The application can call APIs to change the colours used.

+ + SC_ELEMENT_SELECTION_TEXT : colouralpha
+ SCI_SETSELFORE(bool useSetting, colour fore)
+ SC_ELEMENT_SELECTION_BACK : colouralpha
+ SCI_SETSELBACK(bool useSetting, colour back)
+ SCI_SETSELECTIONLAYER(int layer)
+ SCI_GETSELECTIONLAYER → int
+ SCI_SETSELALPHA(alpha alpha)
+ SCI_GETSELALPHA → int
SCI_SETSELEOLFILLED(bool filled)
SCI_GETSELEOLFILLED → bool
- SCI_SETCARETFORE(colour fore)
- SCI_GETCARETFORE → colour
+
+ SC_ELEMENT_CARET : colouralpha
+ SCI_SETCARETFORE(colour fore)
+ SCI_GETCARETFORE → colour
+
+ SC_ELEMENT_SELECTION_SECONDARY_TEXT : colouralpha
+ SC_ELEMENT_SELECTION_SECONDARY_BACK : colouralpha
+ SC_ELEMENT_CARET_SECONDARY : colouralpha
+
+ SC_ELEMENT_SELECTION_NO_FOCUS_TEXT : colouralpha
+ SC_ELEMENT_SELECTION_NO_FOCUS_BACK : colouralpha
+
SCI_SETCARETLINEVISIBLE(bool show)
SCI_GETCARETLINEVISIBLE → bool
SCI_SETCARETLINEBACK(colour back)
@@ -3335,12 +3451,17 @@ struct Sci_TextToFind { SCI_GETCARETLINEFRAME → int
SCI_SETCARETLINEVISIBLEALWAYS(bool alwaysVisible)
SCI_GETCARETLINEVISIBLEALWAYS → bool
+
SCI_SETCARETPERIOD(int periodMilliseconds)
SCI_GETCARETPERIOD → int
SCI_SETCARETSTYLE(int caretStyle)
SCI_GETCARETSTYLE → int
SCI_SETCARETWIDTH(int pixelWidth)
SCI_GETCARETWIDTH → int
+ SCI_SETCARETSTICKY(int useCaretStickyBehaviour)
+ SCI_GETCARETSTICKY → int
+ SCI_TOGGLECARETSTICKY
+
SCI_SETHOTSPOTACTIVEFORE(bool useSetting, colour fore)
SCI_GETHOTSPOTACTIVEFORE → colour
SCI_SETHOTSPOTACTIVEBACK(bool useSetting, colour back)
@@ -3349,31 +3470,87 @@ struct Sci_TextToFind { SCI_GETHOTSPOTACTIVEUNDERLINE → bool
SCI_SETHOTSPOTSINGLELINE(bool singleLine)
SCI_GETHOTSPOTSINGLELINE → bool
- SCI_SETCARETSTICKY(int useCaretStickyBehaviour)
- SCI_GETCARETSTICKY → int
- SCI_TOGGLECARETSTICKY
 -

SCI_SETSELFORE(bool useSetting, colour fore)
+

+ SC_ELEMENT_SELECTION_TEXT : colouralpha
+ SCI_SETSELFORE(bool useSetting, colour fore)
+ SC_ELEMENT_SELECTION_BACK : colouralpha
SCI_SETSELBACK(bool useSetting, colour back)
- You can choose to override the default selection colouring with these two messages. The colour + You can choose to override the default selection colouring with these elements and messages. + The element APIs are now preferred as they handle translucency + layering and + cooperation with defaults better. + With the messages, the colour you provide is used if you set useSetting to true. If it is set to false, the default styled colouring is used and the fore or back argument has no effect.

+ +

SCI_SETSELECTIONLAYER(int layer)
+ SCI_GETSELECTIONLAYER → int
+ The selection background can be drawn translucently over the text + or opaquely on the base layer. + The layer argument can be one of:

+ + + + + + + + + + + + + + + + + + + + +
SC_LAYER_BASE0Draw the selection background opaquely on the base layer
SC_LAYER_OVER_TEXT10Draw the selection background translucently over the text
+

SCI_SETSELALPHA(alpha alpha)
SCI_GETSELALPHA → int
- The selection can be drawn translucently in the selection background colour by - setting an alpha value.

+ These APIs are now discouraged and should be replaced with + a combination of setting the layer with SCI_SETSELECTIONLAYER and + setting translucency through the SC_ELEMENT_SELECTION_BACK element.

SCI_SETSELEOLFILLED(bool filled)
SCI_GETSELEOLFILLED → bool
The selection can be drawn up to the right hand border by setting this property.

-

SCI_SETCARETFORE(colour fore)
+

+ SC_ELEMENT_CARET : colouralpha
+ SCI_SETCARETFORE(colour fore)
SCI_GETCARETFORE → colour
- The colour of the caret can be set with SCI_SETCARETFORE and retrieved with - SCI_GETCARETFORE.

+ The colour of the caret can be set with + SCI_SETELEMENTCOLOUR(SC_ELEMENT_CARET) or + SCI_SETCARETFORE and retrieved with + SCI_GETELEMENTCOLOUR(SC_ELEMENT_CARET) or + SCI_GETCARETFORE. + The element APIs are preferred and allow setting the translucency of carets.

+ +

+ SC_ELEMENT_SELECTION_SECONDARY_TEXT : colouralpha
+ SC_ELEMENT_SELECTION_SECONDARY_TEXT : colouralpha
+ SC_ELEMENT_CARET_SECONDARY : colouralpha
+ On Unix systems running with the X window system or Wayland there is a 'primary selection' which is the text most recently + selected in any application and which can be pasted by a middle button click. + When working with a selection, it is commonly the primary selection so Scintilla draws the primary selection with the main and additional + colours defined earlier. When another application takes over the primary selection, these _SECONDARY colours are used. + They are commonly defined as grey to highlight that it is the selection in the other application that is now available as primary. +

+ +

+ SC_ELEMENT_SELECTION_NO_FOCUS_TEXT : colouralpha
+ SC_ELEMENT_SELECTION_NO_FOCUS_BACK : colouralpha
+ When a window no longer has the keyboard focus, it is customary to make its selection less noticeable by colouring it grey. + These elements define the colours to be used for selections without focus. +

SCI_SETCARETLINEVISIBLE(bool show)
SCI_GETCARETLINEVISIBLE → bool
@@ -3467,19 +3644,6 @@ struct Sci_TextToFind { This setting only affects the width of the cursor when the cursor style is set to line caret mode, it does not affect the width for a block caret.

-

SCI_SETHOTSPOTACTIVEFORE(bool useSetting, colour fore)
- SCI_GETHOTSPOTACTIVEFORE → colour
- SCI_SETHOTSPOTACTIVEBACK(bool useSetting, - colour back)
- SCI_GETHOTSPOTACTIVEBACK → colour
- SCI_SETHOTSPOTACTIVEUNDERLINE(bool underline)
- SCI_GETHOTSPOTACTIVEUNDERLINE → bool
- SCI_SETHOTSPOTSINGLELINE(bool singleLine)
- SCI_GETHOTSPOTSINGLELINE → bool
- While the cursor hovers over text in a style with the hotspot attribute set, - the default colouring can be modified and an underline drawn with these settings. - Single line mode stops a hotspot from wrapping onto next line.

-

SCI_SETCARETSTICKY(int useCaretStickyBehaviour)
SCI_GETCARETSTICKY → int
SCI_TOGGLECARETSTICKY
@@ -3500,6 +3664,19 @@ struct Sci_TextToFind {

SCI_TOGGLECARETSTICKY switches from SC_CARETSTICKY_ON and SC_CARETSTICKY_WHITESPACE to SC_CARETSTICKY_OFF and from SC_CARETSTICKY_OFF to SC_CARETSTICKY_ON.

+

SCI_SETHOTSPOTACTIVEFORE(bool useSetting, colour fore)
+ SCI_GETHOTSPOTACTIVEFORE → colour
+ SCI_SETHOTSPOTACTIVEBACK(bool useSetting, + colour back)
+ SCI_GETHOTSPOTACTIVEBACK → colour
+ SCI_SETHOTSPOTACTIVEUNDERLINE(bool underline)
+ SCI_GETHOTSPOTACTIVEUNDERLINE → bool
+ SCI_SETHOTSPOTSINGLELINE(bool singleLine)
+ SCI_GETHOTSPOTSINGLELINE → bool
+ While the cursor hovers over text in a style with the hotspot attribute set, + the default colouring can be modified and an underline drawn with these settings. + Single line mode stops a hotspot from wrapping onto next line.

+

Character representations

Some characters, such as control characters and invalid bytes, do not have a visual glyph or use a glyph that is hard to distinguish.

@@ -8877,7 +9054,7 @@ for line = lineStart to lineEnd do SCI_ENSUREVISIBLE(line) next provisional status. To avoid using provisional messages compile with the symbol SCI_DISABLE_PROVISIONAL defined.

-

Deprecated messages and notifications

+

Deprecated and discouraged messages and notifications

The following messages are currently supported to emulate existing Windows controls, but they will be removed in future versions of Scintilla. If you use these messages you should @@ -8964,6 +9141,11 @@ EM_FORMATRANGE Any use of these symbols should be removed and replaced with standard indicators. SCI_GETSTYLEBITS and SCI_GETSTYLEBITSNEEDED always return 8, indicating that 8 bits are used for styling and there are 256 styles.

+ +

Discouraged APIs are a step before deprecation. A new preferred API has been implemented that new code should use + but the old API is unlikely to be removed. + Discouraged APIs are marked with a orange strikethrough and their documentation mentions the preferred API. +

Edit messages never supported by Scintilla

-- 
cgit v1.2.3