From 802391bafca9efff2c41fbc31e54f309479ccdea Mon Sep 17 00:00:00 2001 From: Neil Date: Thu, 16 Oct 2014 14:59:25 +1100 Subject: Reordered searching section so preferred SCI_SEARCHINTARGET API is shown first to discourage use of other APIs. Fixed some HTML bugs. --- doc/ScintillaDoc.html | 193 ++++++++++++++++++++++++-------------------------- 1 file changed, 94 insertions(+), 99 deletions(-) (limited to 'doc') diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index 648615821..e21be5e6a 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -82,7 +82,7 @@

Scintilla Documentation

-

Last edited 2 October 2014 NH

+

Last edited 16 October 2014 NH

There is an overview of the internal design of Scintilla.
@@ -606,7 +606,14 @@ struct Sci_TextRange {

Searching

- There are methods to search for text and for regular expressions. The base regular expression support + There are methods to search for text and for regular expressions. + Most applications should use + SCI_SEARCHINTARGET + as the basis for their search implementations. + Other calls augment this or were implemented before SCI_SEARCHINTARGET. +

+

+ The base regular expression support is limited and should only be used for simple cases and initial development. When using a C++11 compliant compiler and runtime, it may be possible to use the runtime's implementation of <regex> by compiling Scintilla with CXX11_REGEX defined. @@ -615,17 +622,81 @@ struct Sci_TextRange { or can be called from the container using direct access to the buffer contents through SCI_GETCHARACTERPOINTER.

- SCI_FINDTEXT(int flags, Sci_TextToFind - *ttf)
- SCI_SEARCHANCHOR
- SCI_SEARCHNEXT(int searchFlags, const char + +

Search and replace using the target

+ +

Searching can be performed within the target range with SCI_SEARCHINTARGET, + which uses a counted string to allow searching for null characters. It returns the + position of the start of the matching text range or -1 for failure, in which case the target is not moved. The flags used by + SCI_SEARCHINTARGET such as SCFIND_MATCHCASE, + SCFIND_WHOLEWORD, SCFIND_WORDSTART, and SCFIND_REGEXP + can be set with SCI_SETSEARCHFLAGS.

+ SCI_SETTARGETSTART(int pos)
+ SCI_GETTARGETSTART
+ SCI_SETTARGETEND(int pos)
+ SCI_GETTARGETEND
+ SCI_TARGETFROMSELECTION
+ SCI_SETSEARCHFLAGS(int searchFlags)
+ SCI_GETSEARCHFLAGS
+ SCI_SEARCHINTARGET(int length, const char *text)
- SCI_SEARCHPREV(int searchFlags, const char + SCI_REPLACETARGET(int length, const char *text)
- Search and replace using the - target
+ SCI_REPLACETARGETRE(int length, const char + *text)
+ SCI_GETTAG(int tagNumber, char *tagValue)
 +

SCI_SETTARGETSTART(int pos)
+ SCI_GETTARGETSTART
+ SCI_SETTARGETEND(int pos)
+ SCI_GETTARGETEND
+ These functions set and return the start and end of the target. When searching + you can set start greater than end to find the last matching text in the + target rather than the first matching text. The target is also set by a successful + SCI_SEARCHINTARGET.

+ +

SCI_TARGETFROMSELECTION
+ Set the target start and end to the start and end positions of the selection.

+ +

SCI_SETSEARCHFLAGS(int searchFlags)
+ SCI_GETSEARCHFLAGS
+ These get and set the searchFlags used by + SCI_SEARCHINTARGET. There are several option flags including a simple regular + expression search.

+ +

SCI_SEARCHINTARGET(int length, const char *text)
+ This searches for the first occurrence of a text string in the target defined by + SCI_SETTARGETSTART and SCI_SETTARGETEND. The text string is not zero + terminated; the size is set by length. The search is modified by the search flags + set by SCI_SETSEARCHFLAGS. If the search succeeds, the target is set to the found + text and the return value is the position of the start of the matching text. If the search + fails, the result is -1.

+ +

SCI_REPLACETARGET(int length, const char *text)
+ If length is -1, text is a zero terminated string, otherwise + length sets the number of character to replace the target with. + After replacement, the target range refers to the replacement text. + The return value + is the length of the replacement string.
+ Note that the recommended way to delete text in the document is to set the target to the text to be removed, + and to perform a replace target with an empty string.

+ +

SCI_REPLACETARGETRE(int length, const char *text)
+ This replaces the target using regular expressions. If length is -1, + text is a zero terminated string, otherwise length is the number of + characters to use. The replacement string is formed from the text string with any sequences of + \1 through \9 replaced by tagged matches from the most recent regular + expression search. \0 is replaced with all the matched text from the most recent search. + After replacement, the target range refers to the replacement text. + The return value is the length of the replacement string.

+ +

SCI_GETTAG(int tagNumber, char *tagValue)
+ Discover what text was matched by tagged expressions in a regular expression search. + This is useful if the application wants to interpret the replacement string itself.

+ +

See also: SCI_FINDTEXT

+

searchFlags
Several of the search routines use flag options, which include a simple regular expression search. Combine the flag options by adding them:

@@ -675,10 +746,6 @@ struct Sci_TextRange { -

You can - search backwards to find the previous occurrence of a search string by setting the end of the - search range before the start.

-

In a regular expression, special characters interpreted are:

@@ -774,12 +841,25 @@ struct Sci_TextRange {

Regular expressions will only match ranges within a single line, never matching over multiple lines.

+ SCI_FINDTEXT(int flags, Sci_TextToFind + *ttf)
+ SCI_SEARCHANCHOR
+ SCI_SEARCHNEXT(int searchFlags, const char + *text)
+ SCI_SEARCHPREV(int searchFlags, const char + *text)
+ +

SCI_FINDTEXT(int searchFlags, Sci_TextToFind *ttf)
This message searches for text in the document. It does not use or move the current selection. The searchFlags argument controls the search type, which includes regular expression searches.

+

You can + search backwards to find the previous occurrence of a search string by setting the end of the + search range before the start.

+

The Sci_TextToFind structure is defined in Scintilla.h; set chrg.cpMin and chrg.cpMax with the range of positions in the document to search. You can search backwards by @@ -832,89 +912,6 @@ struct Sci_TextToFind {

See also: SCI_SEARCHINTARGET, SCI_FINDTEXT

-

Search and replace using the target

- -

Using SCI_REPLACESEL, - modifications cause scrolling and other visible changes, which may take some time and cause - unwanted display updates. If performing many changes, such as a replace all command, the target - can be used instead. First, set the target, ie. the range to be replaced. Then call - SCI_REPLACETARGET or SCI_REPLACETARGETRE.

- -

Searching can be performed within the target range with SCI_SEARCHINTARGET, - which uses a counted string to allow searching for null characters. It returns the - position of the start of the matching text range or -1 for failure, in which case the target is not moved. The flags used by - SCI_SEARCHINTARGET such as SCFIND_MATCHCASE, - SCFIND_WHOLEWORD, SCFIND_WORDSTART, and SCFIND_REGEXP - can be set with SCI_SETSEARCHFLAGS. SCI_SEARCHINTARGET may be simpler - for some clients to use than SCI_FINDTEXT, as that requires using a pointer to a - structure.

- SCI_SETTARGETSTART(int pos)
- SCI_GETTARGETSTART
- SCI_SETTARGETEND(int pos)
- SCI_GETTARGETEND
- SCI_TARGETFROMSELECTION
- SCI_SETSEARCHFLAGS(int searchFlags)
- SCI_GETSEARCHFLAGS
- SCI_SEARCHINTARGET(int length, const char - *text)
- SCI_REPLACETARGET(int length, const char - *text)
- SCI_REPLACETARGETRE(int length, const char - *text)
- SCI_GETTAG(int tagNumber, char *tagValue)
- - -

SCI_SETTARGETSTART(int pos)
- SCI_GETTARGETSTART
- SCI_SETTARGETEND(int pos)
- SCI_GETTARGETEND
- These functions set and return the start and end of the target. When searching in non-regular - expression mode, you can set start greater than end to find the last matching text in the - target rather than the first matching text. The target is also set by a successful - SCI_SEARCHINTARGET.

- -

SCI_TARGETFROMSELECTION
- Set the target start and end to the start and end positions of the selection.

- -

SCI_SETSEARCHFLAGS(int searchFlags)
- SCI_GETSEARCHFLAGS
- These get and set the searchFlags used by - SCI_SEARCHINTARGET. There are several option flags including a simple regular - expression search.

- -

SCI_SEARCHINTARGET(int length, const char *text)
- This searches for the first occurrence of a text string in the target defined by - SCI_SETTARGETSTART and SCI_SETTARGETEND. The text string is not zero - terminated; the size is set by length. The search is modified by the search flags - set by SCI_SETSEARCHFLAGS. If the search succeeds, the target is set to the found - text and the return value is the position of the start of the matching text. If the search - fails, the result is -1.

- -

SCI_REPLACETARGET(int length, const char *text)
- If length is -1, text is a zero terminated string, otherwise - length sets the number of character to replace the target with. - After replacement, the target range refers to the replacement text. - The return value - is the length of the replacement string.
- Note that the recommended way to delete text in the document is to set the target to the text to be removed, - and to perform a replace target with an empty string.

- -

SCI_REPLACETARGETRE(int length, const char *text)
- This replaces the target using regular expressions. If length is -1, - text is a zero terminated string, otherwise length is the number of - characters to use. The replacement string is formed from the text string with any sequences of - \1 through \9 replaced by tagged matches from the most recent regular - expression search. \0 is replaced with all the matched text from the most recent search. - After replacement, the target range refers to the replacement text. - The return value is the length of the replacement string.

- -

SCI_GETTAG(int tagNumber, char *tagValue)
- Discover what text was matched by tagged expressions in a regular expression search. - This is useful if the application wants to interpret the replacement string itself.

- -

See also: SCI_FINDTEXT

-

Overtype

SCI_SETOVERTYPE(bool overType)
@@ -3181,6 +3178,7 @@ struct Sci_TextToFind {

Other settings

+ SCI_SETBUFFEREDDRAW(bool isBuffered)
SCI_GETBUFFEREDDRAW
SCI_SETPHASESDRAW(int phases)
@@ -5539,7 +5537,6 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
-

SCI_EXPANDCHILDREN(int line, int level)
This is used to respond to a change to a line causing its fold level or whether it is a header to change, @@ -7536,8 +7533,6 @@ 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.

-

-

Edit messages never supported by Scintilla

-- 
cgit v1.2.3