From 26bcc5f887292ec59378e048b6da432710e05cde Mon Sep 17 00:00:00 2001 From: Neil Date: Tue, 20 Sep 2016 09:11:51 +1000 Subject: Improved documentation on word functions and moved into a new section. --- doc/ScintillaDoc.html | 378 ++++++++++++++++++++++++++++---------------------- 1 file changed, 214 insertions(+), 164 deletions(-) diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index 8b6e68d4c..92fafbbf6 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -20,6 +20,8 @@ A.message { text-decoration: none; font-weight: bold; font-family: Consolas,Bitstream Vera Sans Mono,Courier New,monospace; } A.toc { text-decoration: none; } A.jump { text-decoration: none; } + LI.message { text-decoration: none; font-weight: bold; font-family: Consolas,Bitstream Vera Sans Mono,Courier New,monospace; } + H2 { background: #E0EAFF; } .S0 { color: #808080; } @@ -82,7 +84,7 @@

Scintilla Documentation

-

Last edited 8 May 2016 NH

+

Last edited 20 September 2016 NH

There is an overview of the internal design of Scintilla.
@@ -250,109 +252,113 @@ o Line endings - o Styling + o Words - o Style definition + o Styling + o Style definition + o Caret, selection, and hotspot styles o Character representations - o Margins - + o Margins + o Annotations o Other settings - o Brace highlighting - + o Brace highlighting + o Tabs and Indentation Guides o Markers - o Indicators - + o Indicators + o Autocompletion o User lists - o Call tips - + o Call tips + o Keyboard commands o Key bindings - o Popup edit menu - + o Popup edit menu + o Macro recording o Printing - o Direct access - + o Direct access + o Multiple views o Background loading and saving - o Folding - + o Folding + o Line wrapping o Zooming - o Long lines - + o Long lines + o Lexer o Lexer objects - o Notifications - + o Notifications + o Images o GTK+ - o Provisional messages - + o Provisional messages + o Deprecated messages o Edit messages never supported by Scintilla + + o Building Scintilla @@ -1187,11 +1193,6 @@ struct Sci_TextToFind { SCI_GETLINESELSTARTPOSITION(int line)
SCI_GETLINESELENDPOSITION(int line)
SCI_MOVECARETINSIDEVIEW
- SCI_WORDENDPOSITION(int position, bool - onlyWordCharacters)
- SCI_WORDSTARTPOSITION(int position, bool - onlyWordCharacters)
- SCI_ISRANGEWORD(int start, int end)
SCI_POSITIONBEFORE(int position)
SCI_POSITIONAFTER(int position)
SCI_POSITIONRELATIVE(int position, int relative)
@@ -1401,98 +1402,6 @@ struct Sci_TextToFind { If the caret is off the top or bottom of the view, it is moved to the nearest line that is visible to its current position. Any selection is lost.

-

SCI_WORDENDPOSITION(int position, bool - onlyWordCharacters)
- SCI_WORDSTARTPOSITION(int position, bool - onlyWordCharacters)
- These messages return the start and end of words using the same definition of words as used - internally within Scintilla. You can set your own list of characters that count as words with - SCI_SETWORDCHARS. The position - sets the start or the search, which is forwards when searching for the end and backwards when - searching for the start.

- -

SCI_ISRANGEWORD(int start, int end)
- Is the range start..end a word or set of words? This message checks that start is at a word start transition and that - end is at a word end transition. It does not check whether there are any spaces inside the range.

- - SCI_ISRANGEWORD(int start, int end)
- -

Set onlyWordCharacters to true (1) to stop searching at the first - non-word character in the search direction. If onlyWordCharacters is - false (0), the first character in the search direction sets the type of the search - as word or non-word and the search stops at the first non-matching character. Searches are also - terminated by the start or end of the document.

- -

If "w" represents word characters and "." represents non-word characters and "|" represents - the position and true or false is the state of - onlyWordCharacters:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Initial stateend, trueend, falsestart, truestart, false
..ww..|..ww....ww..|..ww....ww....|ww....ww..|..ww....ww|....ww..
....ww|ww........wwww|........wwww|........|wwww........|wwww....
..ww|....ww....ww|....ww....ww....|ww....|ww....ww....|ww....ww..
..ww....|ww....ww....ww|....ww....ww|....ww....|ww....ww|....ww..
-

SCI_POSITIONBEFORE(int position)
SCI_POSITIONAFTER(int position)
These messages return the position before and after another position @@ -2395,6 +2304,191 @@ struct Sci_TextToFind { SCI_GETLINEENDTYPESACTIVE reports the set of line ends currently interpreted by Scintilla. It is SCI_GETLINEENDTYPESSUPPORTED & SCI_GETLINEENDTYPESALLOWED.

+

Words

+ +

There is support for selecting, navigating by, and searching for words.

+ +

+ Words are contiguous sequences of characters from a particular set of characters. + 4 categories define words: word, whitespace, punctuation, and line ends with each category + having a role in word functions. + Double clicking selects the word at that point, which may be a sequence of word, punctuation, + or whitespace bytes. + Line ends are not selected by double clicking but do act as word separators. +

+ +

Words are defined in terms of bytes, not characters so there are some issues with + UTF-8 and DCBS documents.

+ +

Identifiers in programming languages are often sequences of words with capitalisation + (aCamelCaseIdentifier) or underscores (an_under_bar_ident) used to mark word boundaries. + The SCI_WORDPART* commands are used for moving between word parts: + SCI_WORDPARTLEFT, + SCI_WORDPARTLEFTEXTEND, + SCI_WORDPARTRIGHT, and + SCI_WORDPARTRIGHTEXTEND. +

+ + SCI_WORDENDPOSITION(int position, bool + onlyWordCharacters)
+ SCI_WORDSTARTPOSITION(int position, bool + onlyWordCharacters)
+ SCI_ISRANGEWORD(int start, int end)
+ + SCI_SETWORDCHARS(<unused>, const char *characters)
+ SCI_GETWORDCHARS(<unused>, char *characters)
+ SCI_SETWHITESPACECHARS(<unused>, const char *characters)
+ SCI_GETWHITESPACECHARS(<unused>, char *characters)
+ SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)
+ SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)
+ SCI_SETCHARSDEFAULT
+ +

SCI_WORDENDPOSITION(int position, bool + onlyWordCharacters)
+ SCI_WORDSTARTPOSITION(int position, bool + onlyWordCharacters)
+ These messages return the start and end of words using the same definition of words as used + internally within Scintilla. You can set your own list of characters that count as words with + SCI_SETWORDCHARS. The position + sets the start or the search, which is forwards when searching for the end and backwards when + searching for the start.

+ +

SCI_ISRANGEWORD(int start, int end)
+ Is the range start..end a word or set of words? This message checks that start is at a word start transition and that + end is at a word end transition. It does not check whether there are any spaces inside the range.

+ + SCI_ISRANGEWORD(int start, int end)
+ +

Set onlyWordCharacters to true (1) to stop searching at the first + non-word character in the search direction. If onlyWordCharacters is + false (0), the first character in the search direction sets the type of the search + as word or non-word and the search stops at the first non-matching character. Searches are also + terminated by the start or end of the document.

+ +

If "w" represents word characters and "." represents non-word characters and "|" represents + the position and true or false is the state of + onlyWordCharacters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Initial stateend, trueend, falsestart, truestart, false
..ww..|..ww....ww..|..ww....ww....|ww....ww..|..ww....ww|....ww..
....ww|ww........wwww|........wwww|........|wwww........|wwww....
..ww|....ww....ww|....ww....ww....|ww....|ww....ww....|ww....ww..
..ww....|ww....ww....ww|....ww....ww|....ww....|ww....ww|....ww..
+ +

SCI_SETWORDCHARS(<unused>, const char *characters)
+ This message defines which characters (bytes) are members of the word category. + The character categories are set to default values before processing this function. + For example, if you don't allow '_' in your set of characters + use:
+ SCI_SETWORDCHARS(0, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789");

+ +

SCI_GETWORDCHARS(<unused>, char *characters)
+ This fills the characters parameter with all the characters included in words. + The characters parameter must be large enough to hold all of the characters. + If the characters parameter is 0 then the length that should be allocated + to store the entire set is returned.

+ +

SCI_SETWHITESPACECHARS(<unused>, const char *characters)
+ SCI_GETWHITESPACECHARS(<unused>, char *characters)
+ Similar to SCI_SETWORDCHARS, this message allows the user to define which chars Scintilla considers + as whitespace. Setting the whitespace chars allows the user to fine-tune Scintilla's behaviour doing + such things as moving the cursor to the start or end of a word; for example, by defining punctuation chars + as whitespace, they will be skipped over when the user presses ctrl+left or ctrl+right. + This function should be called after SCI_SETWORDCHARS as it will + reset the whitespace characters to the default set. + SCI_GETWHITESPACECHARS behaves similarly to SCI_GETWORDCHARS.

+ +

SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)
+ SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)
+ Similar to SCI_SETWORDCHARS and SCI_SETWHITESPACECHARS, this message + allows the user to define which chars Scintilla considers as punctuation. + SCI_GETPUNCTUATIONCHARS behaves similarly to SCI_GETWORDCHARS.

+ +

SCI_SETCHARSDEFAULT
+ Use the default sets of word and whitespace characters. This sets whitespace to space, tab and other + characters with codes less than 0x20, with word characters set to alphanumeric and '_'. +

+ +

Word keyboard commands are: +

+

+

Styling

The styling messages allow you to assign styles to text. If your styling needs can be met by @@ -3339,13 +3433,6 @@ struct Sci_TextToFind { SCI_GETCODEPAGE
SCI_SETIMEINTERACTION(int imeInteraction)
SCI_GETIMEINTERACTION
- SCI_SETWORDCHARS(<unused>, const char *characters)
- SCI_GETWORDCHARS(<unused>, char *characters)
- SCI_SETWHITESPACECHARS(<unused>, const char *characters)
- SCI_GETWHITESPACECHARS(<unused>, char *characters)
- SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)
- SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)
- SCI_SETCHARSDEFAULT
SCI_GRABFOCUS
SCI_SETFOCUS(bool focus)
SCI_GETFOCUS
@@ -3475,43 +3562,6 @@ struct Sci_TextToFind { and the inline behaviour with SCI_SETIMEINTERACTION(SC_IME_INLINE). Scintilla may ignore this call in some cases. For example, the inline behaviour might only be supported for some languages.

-

SCI_SETWORDCHARS(<unused>, const char *characters)
- Scintilla has several functions that operate on words, which are defined to be contiguous - sequences of characters from a particular set of characters. This message defines which - characters are members of that set. The character sets are set to default values before processing this - function. - For example, if you don't allow '_' in your set of characters - use:
- SCI_SETWORDCHARS(0, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789");

- -

SCI_GETWORDCHARS(<unused>, char *characters)
- This fills the characters parameter with all the characters included in words. - The characters parameter must be large enough to hold all of the characters. - If the characters parameter is 0 then the length that should be allocated - to store the entire set is returned.

- -

SCI_SETWHITESPACECHARS(<unused>, const char *characters)
- SCI_GETWHITESPACECHARS(<unused>, char *characters)
- Similar to SCI_SETWORDCHARS, this message allows the user to define which chars Scintilla considers - as whitespace. Setting the whitespace chars allows the user to fine-tune Scintilla's behaviour doing - such things as moving the cursor to the start or end of a word; for example, by defining punctuation chars - as whitespace, they will be skipped over when the user presses ctrl+left or ctrl+right. - This function should be called after SCI_SETWORDCHARS as it will - reset the whitespace characters to the default set. - SCI_GETWHITESPACECHARS behaves similarly to SCI_GETWORDCHARS.

- -

SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)
- SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)
- Similar to SCI_SETWORDCHARS and SCI_SETWHITESPACECHARS, this message - allows the user to define which chars Scintilla considers as punctuation. - SCI_GETPUNCTUATIONCHARS behaves similarly to SCI_GETWORDCHARS.

- -

SCI_SETCHARSDEFAULT
- Use the default sets of word and whitespace characters. This sets whitespace to space, tab and other - characters with codes less than 0x20, with word characters set to alphanumeric and '_'. -

- -

SCI_GRABFOCUS
SCI_SETFOCUS(bool focus)
SCI_GETFOCUS
-- cgit v1.2.3