diff options
| -rw-r--r-- | doc/ScintillaDoc.html | 193 |
1 files changed, 94 insertions, 99 deletions
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 @@ <h1>Scintilla Documentation</h1> - <p>Last edited 2 October 2014 NH</p> + <p>Last edited 16 October 2014 NH</p> <p>There is <a class="jump" href="Design.html">an overview of the internal design of Scintilla</a>.<br /> @@ -606,7 +606,14 @@ struct Sci_TextRange { <h2 id="Searching">Searching</h2> <p> - 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 + <a class="message" href="#SCI_SEARCHINTARGET">SCI_SEARCHINTARGET</a> + as the basis for their search implementations. + Other calls augment this or were implemented before <code>SCI_SEARCHINTARGET</code>. + </p> + <p> + The base regular expression support is limited and should only be used for simple cases and initial development. <span class="provisional">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 <code>CXX11_REGEX</code> defined.</span> @@ -615,17 +622,81 @@ struct Sci_TextRange { or can be called from the container using direct access to the buffer contents through <a class="message" href="#SCI_GETCHARACTERPOINTER">SCI_GETCHARACTERPOINTER</a>. </p> - <code><a class="message" href="#SCI_FINDTEXT">SCI_FINDTEXT(int flags, Sci_TextToFind - *ttf)</a><br /> - <a class="message" href="#SCI_SEARCHANCHOR">SCI_SEARCHANCHOR</a><br /> - <a class="message" href="#SCI_SEARCHNEXT">SCI_SEARCHNEXT(int searchFlags, const char + + <h3 id="SearchAndReplaceUsingTheTarget">Search and replace using the target</h3> + + <p>Searching can be performed within the target range with <code>SCI_SEARCHINTARGET</code>, + 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 + <code>SCI_SEARCHINTARGET</code> such as <code>SCFIND_MATCHCASE</code>, + <code>SCFIND_WHOLEWORD</code>, <code>SCFIND_WORDSTART</code>, and <code>SCFIND_REGEXP</code> + can be set with <code>SCI_SETSEARCHFLAGS</code>.</p> + <code><a class="message" href="#SCI_SETTARGETSTART">SCI_SETTARGETSTART(int pos)</a><br /> + <a class="message" href="#SCI_GETTARGETSTART">SCI_GETTARGETSTART</a><br /> + <a class="message" href="#SCI_SETTARGETEND">SCI_SETTARGETEND(int pos)</a><br /> + <a class="message" href="#SCI_GETTARGETEND">SCI_GETTARGETEND</a><br /> + <a class="message" href="#SCI_TARGETFROMSELECTION">SCI_TARGETFROMSELECTION</a><br /> + <a class="message" href="#SCI_SETSEARCHFLAGS">SCI_SETSEARCHFLAGS(int searchFlags)</a><br /> + <a class="message" href="#SCI_GETSEARCHFLAGS">SCI_GETSEARCHFLAGS</a><br /> + <a class="message" href="#SCI_SEARCHINTARGET">SCI_SEARCHINTARGET(int length, const char *text)</a><br /> - <a class="message" href="#SCI_SEARCHPREV">SCI_SEARCHPREV(int searchFlags, const char + <a class="message" href="#SCI_REPLACETARGET">SCI_REPLACETARGET(int length, const char *text)</a><br /> - <a class="jump" href="#SearchAndReplaceUsingTheTarget">Search and replace using the - target</a><br /> + <a class="message" href="#SCI_REPLACETARGETRE">SCI_REPLACETARGETRE(int length, const char + *text)</a><br /> + <a class="message" href="#SCI_GETTAG">SCI_GETTAG(int tagNumber, char *tagValue)</a><br /> </code> + <p><b id="SCI_SETTARGETSTART">SCI_SETTARGETSTART(int pos)</b><br /> + <b id="SCI_GETTARGETSTART">SCI_GETTARGETSTART</b><br /> + <b id="SCI_SETTARGETEND">SCI_SETTARGETEND(int pos)</b><br /> + <b id="SCI_GETTARGETEND">SCI_GETTARGETEND</b><br /> + 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 + <code>SCI_SEARCHINTARGET</code>.</p> + + <p><b id="SCI_TARGETFROMSELECTION">SCI_TARGETFROMSELECTION</b><br /> + Set the target start and end to the start and end positions of the selection.</p> + + <p><b id="SCI_SETSEARCHFLAGS">SCI_SETSEARCHFLAGS(int searchFlags)</b><br /> + <b id="SCI_GETSEARCHFLAGS">SCI_GETSEARCHFLAGS</b><br /> + These get and set the <a class="jump" href="#searchFlags"><code>searchFlags</code></a> used by + <code>SCI_SEARCHINTARGET</code>. There are several option flags including a simple regular + expression search.</p> + + <p><b id="SCI_SEARCHINTARGET">SCI_SEARCHINTARGET(int length, const char *text)</b><br /> + This searches for the first occurrence of a text string in the target defined by + <code>SCI_SETTARGETSTART</code> and <code>SCI_SETTARGETEND</code>. The text string is not zero + terminated; the size is set by <code>length</code>. The search is modified by the search flags + set by <code>SCI_SETSEARCHFLAGS</code>. 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.</p> + + <p><b id="SCI_REPLACETARGET">SCI_REPLACETARGET(int length, const char *text)</b><br /> + If <code>length</code> is -1, <code>text</code> is a zero terminated string, otherwise + <code>length</code> 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.<br /> + 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.</p> + + <p><b id="SCI_REPLACETARGETRE">SCI_REPLACETARGETRE(int length, const char *text)</b><br /> + This replaces the target using regular expressions. If <code>length</code> is -1, + <code>text</code> is a zero terminated string, otherwise <code>length</code> is the number of + characters to use. The replacement string is formed from the text string with any sequences of + <code>\1</code> through <code>\9</code> replaced by tagged matches from the most recent regular + expression search. <code>\0</code> 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.</p> + + <p><b id="SCI_GETTAG">SCI_GETTAG(int tagNumber, char *tagValue)</b><br /> + 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.</p> + + <p>See also: <a class="message" href="#SCI_FINDTEXT"><code>SCI_FINDTEXT</code></a></p> + <p><b id="searchFlags"><code>searchFlags</code></b><br /> Several of the search routines use flag options, which include a simple regular expression search. Combine the flag options by adding them:</p> @@ -675,10 +746,6 @@ struct Sci_TextRange { </tbody> </table> - <p>You can - search backwards to find the previous occurrence of a search string by setting the end of the - search range before the start.</p> - <p>In a regular expression, special characters interpreted are:</p> <table border="0" summary="Regular expression synopsis"> @@ -774,12 +841,25 @@ struct Sci_TextRange { <p>Regular expressions will only match ranges within a single line, never matching over multiple lines.</p> + <code><a class="message" href="#SCI_FINDTEXT">SCI_FINDTEXT(int flags, Sci_TextToFind + *ttf)</a><br /> + <a class="message" href="#SCI_SEARCHANCHOR">SCI_SEARCHANCHOR</a><br /> + <a class="message" href="#SCI_SEARCHNEXT">SCI_SEARCHNEXT(int searchFlags, const char + *text)</a><br /> + <a class="message" href="#SCI_SEARCHPREV">SCI_SEARCHPREV(int searchFlags, const char + *text)</a><br /> + </code> + <p><b id="SCI_FINDTEXT">SCI_FINDTEXT(int searchFlags, <a class="jump" href="#Sci_TextToFind">Sci_TextToFind</a> *ttf)</b><br /> This message searches for text in the document. It does not use or move the current selection. The <a class="jump" href="#searchFlags"><code>searchFlags</code></a> argument controls the search type, which includes regular expression searches.</p> + <p>You can + search backwards to find the previous occurrence of a search string by setting the end of the + search range before the start.</p> + <p>The <code>Sci_TextToFind</code> structure is defined in <code>Scintilla.h</code>; set <code>chrg.cpMin</code> and <code>chrg.cpMax</code> with the range of positions in the document to search. You can search backwards by @@ -832,89 +912,6 @@ struct Sci_TextToFind { <p>See also: <a class="message" href="#SCI_SEARCHINTARGET"><code>SCI_SEARCHINTARGET</code></a>, <a class="message" href="#SCI_FINDTEXT"><code>SCI_FINDTEXT</code></a></p> - <h3 id="SearchAndReplaceUsingTheTarget">Search and replace using the target</h3> - - <p>Using <a class="message" href="#SCI_REPLACESEL"><code>SCI_REPLACESEL</code></a>, - 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 - <code>SCI_REPLACETARGET</code> or <code>SCI_REPLACETARGETRE</code>.</p> - - <p>Searching can be performed within the target range with <code>SCI_SEARCHINTARGET</code>, - 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 - <code>SCI_SEARCHINTARGET</code> such as <code>SCFIND_MATCHCASE</code>, - <code>SCFIND_WHOLEWORD</code>, <code>SCFIND_WORDSTART</code>, and <code>SCFIND_REGEXP</code> - can be set with <code>SCI_SETSEARCHFLAGS</code>. <code>SCI_SEARCHINTARGET</code> may be simpler - for some clients to use than <a class="message" - href="#SCI_FINDTEXT"><code>SCI_FINDTEXT</code></a>, as that requires using a pointer to a - structure.</p> - <code><a class="message" href="#SCI_SETTARGETSTART">SCI_SETTARGETSTART(int pos)</a><br /> - <a class="message" href="#SCI_GETTARGETSTART">SCI_GETTARGETSTART</a><br /> - <a class="message" href="#SCI_SETTARGETEND">SCI_SETTARGETEND(int pos)</a><br /> - <a class="message" href="#SCI_GETTARGETEND">SCI_GETTARGETEND</a><br /> - <a class="message" href="#SCI_TARGETFROMSELECTION">SCI_TARGETFROMSELECTION</a><br /> - <a class="message" href="#SCI_SETSEARCHFLAGS">SCI_SETSEARCHFLAGS(int searchFlags)</a><br /> - <a class="message" href="#SCI_GETSEARCHFLAGS">SCI_GETSEARCHFLAGS</a><br /> - <a class="message" href="#SCI_SEARCHINTARGET">SCI_SEARCHINTARGET(int length, const char - *text)</a><br /> - <a class="message" href="#SCI_REPLACETARGET">SCI_REPLACETARGET(int length, const char - *text)</a><br /> - <a class="message" href="#SCI_REPLACETARGETRE">SCI_REPLACETARGETRE(int length, const char - *text)</a><br /> - <a class="message" href="#SCI_GETTAG">SCI_GETTAG(int tagNumber, char *tagValue)</a><br /> - </code> - - <p><b id="SCI_SETTARGETSTART">SCI_SETTARGETSTART(int pos)</b><br /> - <b id="SCI_GETTARGETSTART">SCI_GETTARGETSTART</b><br /> - <b id="SCI_SETTARGETEND">SCI_SETTARGETEND(int pos)</b><br /> - <b id="SCI_GETTARGETEND">SCI_GETTARGETEND</b><br /> - 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 - <code>SCI_SEARCHINTARGET</code>.</p> - - <p><b id="SCI_TARGETFROMSELECTION">SCI_TARGETFROMSELECTION</b><br /> - Set the target start and end to the start and end positions of the selection.</p> - - <p><b id="SCI_SETSEARCHFLAGS">SCI_SETSEARCHFLAGS(int searchFlags)</b><br /> - <b id="SCI_GETSEARCHFLAGS">SCI_GETSEARCHFLAGS</b><br /> - These get and set the <a class="jump" href="#searchFlags"><code>searchFlags</code></a> used by - <code>SCI_SEARCHINTARGET</code>. There are several option flags including a simple regular - expression search.</p> - - <p><b id="SCI_SEARCHINTARGET">SCI_SEARCHINTARGET(int length, const char *text)</b><br /> - This searches for the first occurrence of a text string in the target defined by - <code>SCI_SETTARGETSTART</code> and <code>SCI_SETTARGETEND</code>. The text string is not zero - terminated; the size is set by <code>length</code>. The search is modified by the search flags - set by <code>SCI_SETSEARCHFLAGS</code>. 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.</p> - - <p><b id="SCI_REPLACETARGET">SCI_REPLACETARGET(int length, const char *text)</b><br /> - If <code>length</code> is -1, <code>text</code> is a zero terminated string, otherwise - <code>length</code> 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.<br /> - 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.</p> - - <p><b id="SCI_REPLACETARGETRE">SCI_REPLACETARGETRE(int length, const char *text)</b><br /> - This replaces the target using regular expressions. If <code>length</code> is -1, - <code>text</code> is a zero terminated string, otherwise <code>length</code> is the number of - characters to use. The replacement string is formed from the text string with any sequences of - <code>\1</code> through <code>\9</code> replaced by tagged matches from the most recent regular - expression search. <code>\0</code> 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.</p> - - <p><b id="SCI_GETTAG">SCI_GETTAG(int tagNumber, char *tagValue)</b><br /> - 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.</p> - - <p>See also: <a class="message" href="#SCI_FINDTEXT"><code>SCI_FINDTEXT</code></a></p> - <h2 id="Overtype">Overtype</h2> <p><b id="SCI_SETOVERTYPE">SCI_SETOVERTYPE(bool overType)</b><br /> @@ -3181,6 +3178,7 @@ struct Sci_TextToFind { </p> <h2 id="OtherSettings">Other settings</h2> + <code> <a class="message" href="#SCI_SETBUFFEREDDRAW">SCI_SETBUFFEREDDRAW(bool isBuffered)</a><br /> <a class="message" href="#SCI_GETBUFFEREDDRAW">SCI_GETBUFFEREDDRAW</a><br /> <a class="message" href="#SCI_SETPHASESDRAW">SCI_SETPHASESDRAW(int phases)</a><br /> @@ -5539,7 +5537,6 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ </tbody> </table> - <p></p> <p><b id="SCI_EXPANDCHILDREN">SCI_EXPANDCHILDREN(int line, int level)</b><br /> 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 <a href="#Indicators">standard indicators</a>. <code>SCI_GETSTYLEBITS</code> and <code>SCI_GETSTYLEBITSNEEDED</code> always return 8, indicating that 8 bits are used for styling and there are 256 styles.</p> - </p> - <h2 id="EditMessagesNeverSupportedByScintilla">Edit messages never supported by Scintilla</h2> <pre> |