| blob | a808c9b5f00c4f9d0666dc0e78541082c3b1cec9 |
6 <head>
15 <!--
16 /*<![CDATA[*/
17 CODE { font-weight: bold; font-family: Consolas,Bitstream Vera Sans Mono,Courier New,monospace; }
18 A:visited { color: blue; }
19 A:hover { text-decoration: underline ! important; }
20 A.message { text-decoration: none; font-weight: bold; font-family: Consolas,Bitstream Vera Sans Mono,Courier New,monospace; }
21 A.toc { text-decoration: none; }
22 A.jump { text-decoration: none; }
23 .S0 {
24 color: #808080;
25 }
26 .S2 {
27 font-family: 'Comic Sans MS';
28 color: #007F00;
29 font-size: 9pt;
30 }
31 .S3 {
32 font-family: 'Comic Sans MS';
33 color: #3F703F;
34 font-size: 9pt;
35 }
36 .S4 {
37 color: #007F7F;
38 }
39 .S5 {
40 font-weight: bold;
41 color: #00007F;
42 }
43 .S9 {
44 color: #7F7F00;
45 }
46 .S10 {
47 font-weight: bold;
48 color: #000000;
49 }
50 .S17 {
51 font-family: 'Comic Sans MS';
52 color: #3060A0;
53 font-size: 9pt;
54 }
55 DIV.highlighted {
56 background: #F7FCF7;
57 border: 1px solid #C0D7C0;
58 margin: 0.3em 3em;
59 padding: 0.3em 0.6em;
60 font-family: 'Verdana';
61 color: #000000;
62 font-size: 10pt;
63 }
64 .provisional {
65 background: #FFB000;
66 }
67 /*]]>*/
68 -->
69 </style>
70 </head>
75 <tr>
80 </tr>
81 </table>
103 <a class="jump" href="https://bitbucket.org/StarFire/scintilla-doc/downloads/Scintilla-var'aq-Tutorial.pdf">
106 worth following if you want to contribute code to Scintilla but is not compulsory.</p>
110 <p>The Windows version of Scintilla is a Windows Control. As such, its primary programming
111 interface is through Windows messages. Early versions of Scintilla emulated much of the API
112 defined by the standard Windows Edit and RichEdit controls but those APIs are now deprecated in
113 favour of Scintilla's own, more consistent API. In addition to messages performing the actions
114 of a normal Edit control, Scintilla allows control of syntax styling, folding, markers, autocompletion
115 and call tips.</p>
117 <p>The GTK+ version also uses messages in a similar way to the Windows version. This is
118 different to normal GTK+ practice but made it easier to implement rapidly.</p>
120 <p>Scintilla also builds with Cocoa on OS X and with Qt, and follows the conventions of
121 those platforms.</p>
123 <p>Scintilla does not properly support right-to-left languages like Arabic and Hebrew.
124 While text in these languages may appear correct, it is not possible to interact with this text
125 as is normal with other editing components.</p>
127 <p>This documentation describes the individual messages and notifications used by Scintilla. It
128 does not describe how to link them together to form a useful editor. For now, the best way to
129 work out how to develop using Scintilla is to see how SciTE uses it. SciTE exercises most of
130 Scintilla's facilities.</p>
132 <p>In the descriptions that follow, the messages are described as function calls with zero, one
135 are large enough to hold pointers, and the return value is also an integer large enough to contain a
136 pointer.
137 Although the commands only use the
138 arguments described, because all messages have two arguments whether Scintilla uses them or
139 not, it is strongly recommended that any unused arguments are set to 0. This allows future
140 enhancement of messages without the risk of breaking existing code. Common argument types
141 are:</p>
145 <tr>
150 </tr>
152 <tr>
156 </tr>
158 <tr>
161 <td>Arguments point at text that is being passed to Scintilla but not modified. The text
162 may be zero terminated or another argument may specify the character count, the
163 description will make this clear.</td>
164 </tr>
166 <tr>
169 <td>Arguments point at text buffers that Scintilla will fill with text. In some cases,
170 another argument will tell Scintilla the buffer size. In others, you must make sure that
171 the buffer is big enough to hold the requested text. If a NULL pointer (0) is passed
172 then, for SCI_* calls, the length that should be allocated is returned.</td>
173 </tr>
175 <tr>
178 <td>Colours are set using the RGB format (Red, Green, Blue). The intensity of each colour
181 colour is white. If you set all intensities to 0, the colour is black. When you set a
182 colour, you are making a request. What you will get depends on the capabilities of the
183 system and the current screen mode.</td>
184 </tr>
186 <tr>
189 <td>Translucency is set using an alpha value.
190 Alpha ranges from 0 (SC_ALPHA_TRANSPARENT) which is completely transparent to
192 is opaque and uses code that is not alpha-aware and may be faster. Not all platforms support
193 translucency and only some Scintilla features implement translucency.
194 The default alpha value for most features is SC_ALPHA_NOALPHA.</td>
195 </tr>
197 <tr>
201 enhancements.</td>
202 </tr>
203 </tbody>
204 </table>
209 <tbody>
210 <tr>
212 modification</a></td>
218 </tr>
220 <tr>
227 </tr>
229 <tr>
232 <td>o <a class="toc" href="#MultipleSelectionAndVirtualSpace">Multiple Selection and Virtual Space</a></td>
235 scrolling</a></td>
237 </tr>
239 <tr>
246 </tr>
248 <tr>
255 </tr>
257 <tr>
258 <td>o <a class="toc" href="#CaretAndSelectionStyles">Caret, selection, and hotspot styles</a></td>
264 </tr>
266 <tr>
273 </tr>
275 <tr>
277 Guides</a></td>
283 </tr>
285 <tr>
292 </tr>
294 <tr>
301 </tr>
303 <tr>
310 </tr>
312 <tr>
319 </tr>
321 <tr>
328 </tr>
330 <tr>
337 </tr>
339 <tr>
344 <td>o <a class="toc" href="#ProvisionalMessages"><span class="provisional">Provisional messages</span></a></td>
346 </tr>
348 <tr>
352 supported by Scintilla</a></td>
356 </tr>
357 </tbody>
358 </table>
367 <p>Each byte in a Scintilla document is associated with a byte of styling
368 information. The combination of a character byte and a style byte is called a cell. Style bytes
369 are interpreted an index into an array of styles.</p>
371 <p>In this document, 'character' normally refers to a byte even when multi-byte characters are used.
372 Lengths measure the numbers of bytes, not the amount of characters in those bytes.</p>
374 <p>Positions within the Scintilla document refer to a character or the gap before that
377 The caret exists between character positions and can be located from before the first character (0)
380 <p>There are places where the caret can not go where two character bytes make up one character.
381 This occurs when a DBCS character from a language like Japanese is included in the document or
382 when line ends are marked with the CP/M standard of a carriage return followed by a line feed.
384 document.</p>
386 <p>All lines of text in Scintilla are the same height, and this height is calculated from the
387 largest font in any current style. This restriction is for performance; if lines differed in
388 height then calculations involving positioning of text would require the text to be styled
389 first.</p>
395 *text)</a><br />
399 *tr)</a><br />
405 <a class="message" href="#SCI_CHANGEINSERTION">SCI_CHANGEINSERTION(int length, const char *text)</a><br />
412 *tr)</a><br />
414 <a class="message" href="#SCI_ALLOCATEEXTENDEDSTYLES">SCI_ALLOCATEEXTENDEDSTYLES(int numberStyles)</a><br />
416 <a class="message" href="#SCI_ENCODEDFROMUTF8">SCI_ENCODEDFROMUTF8(const char *utf8, char *encoded)</a><br />
418 </code>
426 entire document is returned.
428 the text as unmodified.</p>
437 This replaces all the text in the document with the zero terminated text string you pass
438 in.</p>
441 This message tells Scintilla that the current state of the document is unmodified. This is
442 usually done when the file is saved or loaded, hence the name "save point". As Scintilla
443 performs undo and redo operations, it notifies the container that it has entered or left the
448 should be considered dirty or not.</p>
454 This fills the buffer defined by text with the contents of the nominated line (lines start at
458 number of characters copied to the buffer. The returned text includes any end of line
459 characters. If you ask for a line number outside the range of lines in the document, 0
460 characters are copied. If the text argument is 0 then the length that should be allocated
461 to store the entire line is returned.</p>
472 current position are the same, the text is inserted at the caret position. The caret is
473 positioned after the inserted text and the caret is scrolled into view.</p>
477 These messages set and get the read-only flag for the document. If you mark a document as read
487 longer than the number of characters you wish to read. The return value is the length of the
498 This collects styled text into a buffer using two bytes for each cell, with the character at
499 the lower address of each pair and the style byte at the upper address. Characters between the
501 <code>struct Sci_TextRange</code> in <code>Scintilla.h</code>). Two 0 bytes are added to the end of
514 Allocate a document buffer large enough to store a given number of bytes.
515 The document will not be made smaller than its current contents.</p>
519 at the current position. This will include any 0's in the string that you might have expected
520 to stop the insert operation. The current position is set at the end of the inserted text,
521 but it is not scrolled into view.</p>
528 of the document. This will include any 0's in the string that you might have expected to stop
529 the operation. The current selection is not changed and the new text is not scrolled into
530 view.</p>
534 the current position if <code>pos</code> is -1. If the current position is after the insertion point
535 then it is moved along with its surrounding text but no scrolling is performed.</p>
538 This may only be called from a <a class="message" href="#SC_MOD_INSERTCHECK">SC_MOD_INSERTCHECK</a>
539 notification handler and will change the text being inserted to that provided.</p>
542 Unless the document is read-only, this deletes all the text.</p>
545 Deletes a range of text in the document.</p>
548 When wanting to completely restyle the document, for example after choosing a lexer, the
550 folding state.</p>
554 negative or past the end of the document.</p>
558 negative or past the end of the document.</p>
562 Extended styles are used for features like textual margins and annotations as well as internally by Scintilla.
564 These functions manage the use of extended styles to ensures that components cooperate in defining styles.
565 <code>SCI_RELEASEALLEXTENDEDSTYLES</code> releases any extended styles allocated by the container.
566 <code>SCI_ALLOCATEEXTENDEDSTYLES</code> allocates a range of style numbers after the byte style values and returns
567 the number of the first allocated style.
568 Ranges for margin and annotation styles should be allocated before calling
572 <p><b id="Sci_TextRange">Sci_TextRange</b> and <b id="Sci_CharacterRange">Sci_CharacterRange</b><br />
575 work.</p>
576 <pre>
577 struct Sci_CharacterRange {
578 long cpMin;
579 long cpMax;
580 };
582 struct Sci_TextRange {
583 struct Sci_CharacterRange chrg;
584 char *lpstrText;
585 };
586 </pre>
591 This method retrieves the value of the target encoded as UTF-8 which is the default
592 encoding of GTK+ so is useful for retrieving text for use in other parts of the user interface,
593 such as find and replace dialogs. The length of the encoded text in bytes is returned.
594 </p>
599 encoding which is useful for taking the results of a find dialog, for example, and receiving
600 a string of bytes that can be searched for in the document. Since the text can contain nul bytes,
602 length that will be converted. If set to -1, the length is determined by finding a nul byte.
603 The length of the converted string is returned.
604 </p>
608 <p>
609 There are methods to search for text and for regular expressions. The regular expression support
610 is limited and should only be used for simple cases and initial development. A different regular expression
612 or can be called from the container using direct access to the buffer contents through
614 </p>
616 *ttf)</a><br />
619 *text)</a><br />
621 *text)</a><br />
623 target</a><br />
624 </code>
627 Several of the search routines use flag options, which include a simple regular expression
628 search. Combine the flag options by adding them:</p>
631 <tbody>
632 <tr>
636 </tr>
638 <tr>
642 </tr>
644 <tr>
648 </tr>
650 <tr>
654 </tr>
655 <tr>
658 <td>Treat regular expression in a more POSIX compatible manner
659 by interpreting bare ( and ) for tagged sections rather than \( and \).</td>
660 </tr>
661 </tbody>
662 </table>
664 <p>You can
665 search backwards to find the previous occurrence of a search string by setting the end of the
666 search range before the start.</p>
671 <tbody>
672 <tr>
676 </tr>
678 <tr>
682 </tr>
684 <tr>
688 </tr>
690 <tr>
698 </tr>
700 <tr>
704 </tr>
706 <tr>
710 </tr>
712 <tr>
715 <td>This allows you to use a character x that would otherwise have a special meaning. For
716 example, \[ would be interpreted as [ and not as the start of a character set.</td>
717 </tr>
719 <tr>
722 <td>This indicates a set of characters, for example, [abc] means any of the characters a,
723 b or c. You can also use ranges, for example [a-z] for any lower case character.</td>
724 </tr>
726 <tr>
729 <td>The complement of the characters in the set. For example, [^A-Za-z] means any
730 character except an alphabetic character.</td>
731 </tr>
733 <tr>
737 </tr>
739 <tr>
743 </tr>
745 <tr>
750 </tr>
752 <tr>
757 </tr>
758 </tbody>
759 </table>
761 <p>Regular expressions will only match ranges within a single line, never matching over multiple lines.</p>
765 This message searches for text in the document. It does not use or move the current selection.
767 search type, which includes regular expression searches.</p>
771 to search. You can search backwards by
773 Set the <code>lpstrText</code> member of <code>Sci_TextToFind</code> to point at a zero terminated
774 text string holding the search pattern. If your language makes the use of <code>Sci_TextToFind</code>
779 <code>Sci_TextToFind</code> are filled in with the start and end positions of the found text.</p>
785 This structure is defined to have exactly the same shape as the Win32 structure
787 <pre>
788 struct Sci_TextToFind {
789 struct <a class="jump" href="#Sci_CharacterRange">Sci_CharacterRange</a> chrg; // range to search
790 const char *lpstrText; // the search pattern (zero terminated)
791 struct Sci_CharacterRange chrgText; // returned as position of matching text
792 };
793 </pre>
798 These messages provide relocatable search support. This allows multiple incremental
799 interactive searches to be macro recorded while still setting the selection to found text so
806 selection, that is, the end of the selection that is nearer to the start of the document. You
811 occurrence of the zero terminated search string pointed at by text. The search is modified by
815 of the matching text. The selection is updated to show the matched text, but is not scrolled
816 into view.</p>
824 modifications cause scrolling and other visible changes, which may take some time and cause
825 unwanted display updates. If performing many changes, such as a replace all command, the target
826 can be used instead. First, set the target, ie. the range to be replaced. Then call
830 which uses a counted string to allow searching for null characters. It returns the
831 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
837 structure.</p>
846 *text)</a><br />
848 *text)</a><br />
850 *text)</a><br />
852 </code>
858 These functions set and return the start and end of the target. When searching in non-regular
859 expression mode, you can set start greater than end to find the last matching text in the
860 target rather than the first matching text. The target is also set by a successful
864 Set the target start and end to the start and end positions of the selection.</p>
870 expression search.</p>
873 This searches for the first occurrence of a text string in the target defined by
877 text and the return value is the position of the start of the matching text. If the search
883 After replacement, the target range refers to the replacement text.
884 The return value
885 is the length of the replacement string.<br />
886 Note that the recommended way to delete text in the document is to set the target to the text to be removed,
887 and to perform a replace target with an empty string.</p>
892 characters to use. The replacement string is formed from the text string with any sequences of
894 expression search. <code>\0</code> is replaced with all the matched text from the most recent search.
895 After replacement, the target range refers to the replacement text.
896 The return value is the length of the replacement string.</p>
899 Discover what text was matched by tagged expressions in a regular expression search.
900 This is useful if the application wants to interpret the replacement string itself.</p>
908 When overtype is enabled, each typed character replaces the character to the right of the text
909 caret. When overtype is disabled, characters are inserted at the caret.
912 mode.</p>
923 const char *text)</a><br />
925 <a class="message" href="#SCI_SETPASTECONVERTENDINGS">SCI_SETPASTECONVERTENDINGS(bool convert)</a><br />
927 </code>
935 These commands perform the standard tasks of cutting and copying data to the clipboard,
936 pasting from the clipboard into the document, and clearing the document.
940 selection ranges implying that a copy or cut to the clipboard should work.</p>
943 unless the document is read-only.</p>
945 <p>On X, the clipboard is asynchronous and may require several messages between
946 the destination and source applications. Data from SCI_PASTE will not arrive in the
947 document immediately.</p>
950 selection is empty then the current line is copied. On Windows, an extra "MSDEVLineSelect" marker
952 the whole line before the current line.</p>
958 text to the system clipboard.</p>
962 If this property is set then when text is pasted any line ends are converted to match the document's
963 end of line mode as set with
965 Defaults to true.</p>
971 If an error occurs, Scintilla may set an internal error number that can be retrieved with
974 The currently defined statuses are:
975 </p>
979 <tr>
983 </tr>
985 <tr>
989 </tr>
991 <tr>
995 </tr>
997 </tbody>
998 </table>
1002 <p>Scintilla has multiple level undo and redo. It will continue to collect undoable actions
1003 until memory runs out. Scintilla saves actions that change the document. Scintilla does not
1004 save caret and selection movements, view scrolling and the like. Sequences of typing or
1005 deleting are compressed into single transactions to make it easier to undo and redo at a sensible
1006 level of detail. Sequences of actions can be combined into transactions that are undone as a unit.
1008 <code>SCI_ENDUNDOACTION</code> messages. These transactions can be nested and only the top-level
1009 sequences are undone as units.</p>
1016 collectUndo)</a><br />
1021 </code>
1029 <p><code>SCI_CANUNDO</code> returns 0 if there is nothing to undo, and 1 if there is. You would
1030 typically use the result of this message to enable/disable the Edit menu Undo command.</p>
1037 actions to redo. You could typically use the result of this message to enable/disable the Edit
1038 menu Redo command.</p>
1041 This command tells Scintilla to forget any saved undo or redo history. It also sets the save
1042 point to the start of the undo buffer, so the document will appear to be unmodified. This does
1045 container.</p>
1051 You can control whether Scintilla collects undo information with
1054 <code>SCI_EMPTYUNDOBUFFER</code> to avoid the undo buffer being unsynchronized with the data in
1055 the buffer.</p>
1057 <p>You might wish to turn off saving undo information if you use the Scintilla to store text
1058 generated by a program (a Log view) or in a display window where text is often deleted and
1059 regenerated.</p>
1063 Send these two messages to Scintilla to mark the beginning and end of a set of operations that
1064 you want to undo all as one operation but that you have to generate as several operations.
1065 Alternatively, you can use these to mark a set of operations that you do not want to have
1066 combined with the preceding or following operations if they are undone.</p>
1069 The container can add its own actions into the undo stack by calling
1071 notification will be sent to the container with the
1076 <p>For example, if the container wanted to allow undo and redo of a 'toggle bookmark' command then
1078 Then when it receives a notification to undo or redo it toggles a bookmark on the line given by
1079 the token field. If there are different types of commands or parameters that need to be stored into the undo
1080 stack then the container should maintain a stack of its own for the document and use the current
1087 coalesced along with any insertion and deletion actions into a single compound action, otherwise 0.
1088 Coalescing treats coalescible container actions as transparent so will still only group together insertions that
1089 look like typing or deletions that look like multiple uses of the Backspace or Delete keys.
1090 </p>
1093 <p>Scintilla maintains a selection that stretches between two points, the anchor and the
1094 current position. If the anchor and the current position are the same, there is no selected
1095 text. Positions in the document range from 0 (before the first character), to the document size
1096 (after the last character). If you use messages, there is nothing to stop you setting a
1097 position that is in the middle of a CRLF pair, or in the middle of a 2 byte character. However,
1098 keyboard commands will not move the caret into such positions.</p>
1102 <a class="message" href="#SCI_SETFIRSTVISIBLELINE">SCI_SETFIRSTVISIBLELINE(int lineDisplay)</a><br />
1127 y)</a><br />
1128 <a class="message" href="#SCI_CHARPOSITIONFROMPOINT">SCI_CHARPOSITIONFROMPOINT(int x, int y)</a><br />
1129 <a class="message" href="#SCI_CHARPOSITIONFROMPOINTCLOSE">SCI_CHARPOSITIONFROMPOINTCLOSE(int x, int
1130 y)</a><br />
1132 position)</a><br />
1134 position)</a><br />
1141 <a class="message" href="#SCI_GETLINESELSTARTPOSITION">SCI_GETLINESELSTARTPOSITION(int line)</a><br />
1142 <a class="message" href="#SCI_GETLINESELENDPOSITION">SCI_GETLINESELENDPOSITION(int line)</a><br />
1145 onlyWordCharacters)</a><br />
1147 onlyWordCharacters)</a><br />
1150 <a class="message" href="#SCI_POSITIONRELATIVE">SCI_POSITIONRELATIVE(int position, int relative)</a><br />
1151 <a class="message" href="#SCI_COUNTCHARACTERS">SCI_COUNTCHARACTERS(int startPos, int endPos)</a><br />
1152 <a class="message" href="#SCI_TEXTWIDTH">SCI_TEXTWIDTH(int styleNumber, const char *text)</a><br />
1157 <a class="message" href="#SCI_SETMOUSESELECTIONRECTANGULARSWITCH">SCI_SETMOUSESELECTIONRECTANGULARSWITCH(bool
1158 mouseSelectionRectangularSwitch)</a><br />
1159 <a class="message" href="#SCI_GETMOUSESELECTIONRECTANGULARSWITCH">SCI_GETMOUSESELECTIONRECTANGULARSWITCH</a><br />
1160 </code>
1164 Both these messages return the length of the document in bytes.</p>
1167 This returns the number of lines in the document. An empty document contains 1 line. A
1172 These messages retrieve and set the line number of the first visible line in the Scintilla view. The first line
1176 This returns the number of complete lines visible on the screen. With a constant line height,
1177 this is the vertical space available divided by the line separation. Unless you arrange to size
1178 your window to an integral number of lines, there may be a partial line visible at the bottom
1179 of the view.</p>
1182 This returns non-zero if the document is modified and 0 if it is unmodified. The modified
1183 status of a document is determined by the undo position relative to the save point. The save
1185 usually when you have saved data to a file.</p>
1187 <p>If you need to be notified when the document becomes modified, Scintilla notifies the
1196 remove any selection (i.e. set the anchor to the same position as <code>currentPos</code>). The
1197 caret is scrolled into view after this operation.</p>
1201 the caret visible, if necessary. It is equivalent to
1203 position.</p>
1207 and scrolls the view (if needed) to make it visible. The anchor position is set the same as the
1209 the line set is the first or last.</p>
1212 This sets the current position and creates a selection between the anchor and the current
1213 position. The caret is not scrolled into view.</p>
1218 This returns the current position.</p>
1221 This sets the anchor position and creates a selection between the anchor position and the
1222 current position. The caret is not scrolled into view.</p>
1227 This returns the current anchor position.</p>
1231 These set the selection based on the assumption that the anchor position is less than the
1232 current position. They do not make the caret visible. The table shows the positions of the
1233 anchor and the current position after using these messages.</p>
1237 <tr>
1238 <th>
1239 </th>
1244 </tr>
1245 </thead>
1248 <tr>
1254 </tr>
1256 <tr>
1262 </tr>
1263 </tbody>
1264 </table>
1270 These return the start and end of the selection without regard to which end is the current
1271 position and which is the anchor. <code>SCI_GETSELECTIONSTART</code> returns the smaller of the
1272 current position or the anchor position. <code>SCI_GETSELECTIONEND</code> returns the larger of
1273 the two values.</p>
1276 This removes any selection and sets the caret at <code>pos</code>. The caret is not scrolled into view.</p>
1279 This selects all the text in the document. The current position is not scrolled into view.</p>
1287 This returns the document position that corresponds with the start of the line. If
1291 last line), the return value is the end of the document.</p>
1294 This returns the position at the end of the line, before any line end characters. If <code>line</code>
1295 is the last line in the document (which does not have any end of line characters) or greater,
1296 the result is the size of the document.
1301 is negative or beyond the last line in the document, the result is 0. If you want the length of
1303 href="#SCI_GETLINEENDPOSITION"><code>SCI_GETLINEENDPOSITION(line)</code></a> - <a class="message"
1308 buffer. The buffer size should be determined by calling with a NULL pointer for the <code>text</code> argument
1310 This allows for rectangular and discontiguous selections as well as simple selections.
1311 See <a class="toc" href="#MultipleSelectionAndVirtualSpace">Multiple Selection</a> for information on
1312 how multiple and rectangular selections and virtual space are copied.</p>
1319 </code></p>
1322 This retrieves the text of the line containing the caret and returns the position within the
1324 the text you wish to retrieve and a terminating 0 character.
1327 If the text argument is 0 then the length that should be allocated
1328 to store the entire current line is returned.</p>
1341 The two functions set and get the selection mode, which can be
1346 When set in these modes, regular caret moves will extend or reduce the selection,
1348 The get function returns the current mode even if the selection was made by mouse
1349 or with regular extended moves.
1350 <code>SC_SEL_THIN</code> is the mode after a rectangular selection has been typed into and ensures
1351 that no characters are selected.</p>
1355 Retrieve the position of the start and end of the selection at the given line with
1359 If the caret is off the top or bottom of the view, it is moved to the nearest line that is
1360 visible to its current position. Any selection is lost.</p>
1363 onlyWordCharacters)</b><br />
1365 onlyWordCharacters)</b><br />
1366 These messages return the start and end of words using the same definition of words as used
1367 internally within Scintilla. You can set your own list of characters that count as words with
1369 sets the start or the search, which is forwards when searching for the end and backwards when
1370 searching for the start.</p>
1374 <code>false</code> (0), the first character in the search direction sets the type of the search
1375 as word or non-word and the search stops at the first non-matching character. Searches are also
1376 terminated by the start or end of the document.</p>
1384 <tr>
1394 </tr>
1395 </thead>
1398 <tr>
1408 </tr>
1410 <tr>
1420 </tr>
1422 <tr>
1432 </tr>
1434 <tr>
1444 </tr>
1445 </tbody>
1446 </table>
1450 These messages return the position before and after another position
1451 in the document taking into account the current code page. The minimum
1452 position returned is 0 and the maximum is the last position in the document.
1453 If called with a position within a multi byte character will return the position
1454 of the start/end of that character.</p>
1457 Count a number of whole characters before or after the argument position and return that position.
1458 The minimum position returned is 0 and the maximum is the last position in the document.
1459 </p>
1462 Returns the number of whole characters between two positions..</p>
1466 be used, for example, to decide how wide to make the line number margin in order to display a
1467 given number of numerals.</p>
1470 This returns the height in pixels of a particular line. Currently all lines are the same
1471 height.</p>
1475 taking the width of tabs into account. This returns the column number of the last tab on the
1477 <code>pos</code>. If there are no tab characters on the line, the return value is the number of
1478 characters up to the position on the line. In both cases, double byte characters count as a
1479 single character. This is probably only useful with monospaced fonts.</p>
1483 taking the width of tabs into account. It treats a multi-byte character as a single column.
1490 window or not close to any characters.</p>
1495 <code>SCI_CHARPOSITIONFROMPOINTCLOSE</code> is similar but returns -1 if the point is outside the
1496 window or not close to any characters. This is similar to the previous methods but finds characters rather than
1497 inter-character positions.</p>
1502 in the document.</p>
1508 is drawn as normal text.</p>
1511 Scintilla remembers the x value of the last position horizontally moved to explicitly by the
1512 user and this value is then used when moving vertically such as by using the up and down keys.
1513 This message sets the current x position of the caret as the remembered value.</p>
1516 Move the selected lines up one line, shifting the line above after the selection.
1517 The selection will be automatically extended to the beginning of the selection's first line and the end of the seletion's last line.
1518 If nothing was selected, the line the cursor is currently at will be selected.</p>
1521 Move the selected lines down one line, shifting the line below before the selection.
1522 The selection will be automatically extended to the beginning of the selection's first line and the end of the seletion's last line.
1523 If nothing was selected, the line the cursor is currently at will be selected.</p>
1526 mouseSelectionRectangularSwitch)</b><br />
1527 <b id="SCI_GETMOUSESELECTIONRECTANGULARSWITCH">SCI_GETMOUSESELECTIONRECTANGULARSWITCH</b><br />
1528 Enable or disable the ability to switch to rectangular selection mode while making a selection with the mouse.
1529 When this option is turned on, mouse selections in stream mode can be switched to rectangular mode by pressing
1530 the corresponding modifier key. They then stick to rectangular mode even when the modifier key is released again.
1531 When this option is turned off, mouse selections will always stick to the mode the selection was started in. It
1532 is off by default.</p>
1536 <code>
1537 <a class="message" href="#SCI_SETMULTIPLESELECTION">SCI_SETMULTIPLESELECTION(bool multipleSelection)</a><br />
1539 <a class="message" href="#SCI_SETADDITIONALSELECTIONTYPING">SCI_SETADDITIONALSELECTIONTYPING(bool additionalSelectionTyping)</a><br />
1540 <a class="message" href="#SCI_GETADDITIONALSELECTIONTYPING">SCI_GETADDITIONALSELECTIONTYPING</a><br />
1543 <a class="message" href="#SCI_SETVIRTUALSPACEOPTIONS">SCI_SETVIRTUALSPACEOPTIONS(int virtualSpaceOptions)</a><br />
1545 <a class="message" href="#SCI_SETRECTANGULARSELECTIONMODIFIER">SCI_SETRECTANGULARSELECTIONMODIFIER(int modifier)</a><br />
1546 <a class="message" href="#SCI_GETRECTANGULARSELECTIONMODIFIER">SCI_GETRECTANGULARSELECTIONMODIFIER</a><br />
1547 <br />
1557 <br />
1559 <a class="message" href="#SCI_SETSELECTIONNCARET">SCI_SETSELECTIONNCARET(int selection, int pos)</a><br />
1560 <a class="message" href="#SCI_GETSELECTIONNCARET">SCI_GETSELECTIONNCARET(int selection)</a><br />
1561 <a class="message" href="#SCI_SETSELECTIONNCARETVIRTUALSPACE">SCI_SETSELECTIONNCARETVIRTUALSPACE(int selection, int space)</a><br />
1562 <a class="message" href="#SCI_GETSELECTIONNCARETVIRTUALSPACE">SCI_GETSELECTIONNCARETVIRTUALSPACE(int selection)</a><br />
1563 <a class="message" href="#SCI_SETSELECTIONNANCHOR">SCI_SETSELECTIONNANCHOR(int selection, int posAnchor)</a><br />
1564 <a class="message" href="#SCI_GETSELECTIONNANCHOR">SCI_GETSELECTIONNANCHOR(int selection)</a><br />
1565 <a class="message" href="#SCI_SETSELECTIONNANCHORVIRTUALSPACE">SCI_SETSELECTIONNANCHORVIRTUALSPACE(int selection, int space)</a><br />
1566 <a class="message" href="#SCI_GETSELECTIONNANCHORVIRTUALSPACE">SCI_GETSELECTIONNANCHORVIRTUALSPACE(int selection)</a><br />
1567 <a class="message" href="#SCI_SETSELECTIONNSTART">SCI_SETSELECTIONNSTART(int selection, int pos)</a><br />
1568 <a class="message" href="#SCI_GETSELECTIONNSTART">SCI_GETSELECTIONNSTART(int selection)</a><br />
1569 <a class="message" href="#SCI_SETSELECTIONNEND">SCI_SETSELECTIONNEND(int selection, int pos)</a><br />
1571 <br />
1573 <a class="message" href="#SCI_SETRECTANGULARSELECTIONCARET">SCI_SETRECTANGULARSELECTIONCARET(int pos)</a><br />
1574 <a class="message" href="#SCI_GETRECTANGULARSELECTIONCARET">SCI_GETRECTANGULARSELECTIONCARET</a><br />
1575 <a class="message" href="#SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE(int space)</a><br />
1576 <a class="message" href="#SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE</a><br />
1577 <a class="message" href="#SCI_SETRECTANGULARSELECTIONANCHOR">SCI_SETRECTANGULARSELECTIONANCHOR(int posAnchor)</a><br />
1578 <a class="message" href="#SCI_GETRECTANGULARSELECTIONANCHOR">SCI_GETRECTANGULARSELECTIONANCHOR</a><br />
1579 <a class="message" href="#SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE(int space)</a><br />
1580 <a class="message" href="#SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE</a><br />
1581 <br />
1583 <a class="message" href="#SCI_SETADDITIONALSELALPHA">SCI_SETADDITIONALSELALPHA(int alpha)</a><br />
1585 <a class="message" href="#SCI_SETADDITIONALSELFORE">SCI_SETADDITIONALSELFORE(int colour)</a><br />
1586 <a class="message" href="#SCI_SETADDITIONALSELBACK">SCI_SETADDITIONALSELBACK(int colour)</a><br />
1587 <a class="message" href="#SCI_SETADDITIONALCARETFORE">SCI_SETADDITIONALCARETFORE(int colour)</a><br />
1589 <a class="message" href="#SCI_SETADDITIONALCARETSBLINK">SCI_SETADDITIONALCARETSBLINK(bool additionalCaretsBlink)</a><br />
1591 <a class="message" href="#SCI_SETADDITIONALCARETSVISIBLE">SCI_SETADDITIONALCARETSVISIBLE(bool additionalCaretsVisible)</a><br />
1592 <a class="message" href="#SCI_GETADDITIONALCARETSVISIBLE">SCI_GETADDITIONALCARETSVISIBLE</a><br />
1593 <br />
1597 </code>
1599 <p>
1600 There may be multiple selections active at one time.
1601 More selections are made by holding down the Ctrl key while dragging with the mouse.
1602 The most recent selection is the main selection and determines which part of the document is shown automatically.
1603 Any selection apart from the main selection is called an additional selection.
1604 The calls in the previous section operate on the main selection.
1605 There is always at least one selection.
1606 </p>
1608 <p>
1609 Rectangular selections are handled as multiple selections although the original rectangular range is remembered so that
1610 subsequent operations may be handled differently for rectangular selections. For example, pasting a rectangular selection
1611 places each piece in a vertical column.
1612 </p>
1614 <p>
1615 Virtual space is space beyond the end of each line. The caret may be moved into virtual space but no real space will be
1616 added to the document until there is some text typed or some other text insertion command is used.
1617 </p>
1619 <p>When discontiguous selections are copied to the clipboard, each selection is added to the clipboard text
1620 in order with no delimiting characters.
1621 For rectangular selections the document's line end is added after each line's text. Rectangular selections
1622 are always copied from top line to bottom, not in the in order of selection.Virtual space is not copied.</p>
1624 <p>
1627 Enable or disable multiple selection. When multiple selection is disabled, it is not possible to select
1628 multiple ranges by holding down the Ctrl key while dragging with the mouse.</p>
1630 <p>
1631 <b id="SCI_SETADDITIONALSELECTIONTYPING">SCI_SETADDITIONALSELECTIONTYPING(bool additionalSelectionTyping)</b><br />
1633 Whether typing, backspace, or delete works with multiple selections simultaneously.</p>
1635 <p>
1638 When pasting into multiple selections, the pasted text can go into just the main selection with <code>SC_MULTIPASTE_ONCE</code>=0
1639 or into each selection with <code>SC_MULTIPASTE_EACH</code>=1. <code>SC_MULTIPASTE_ONCE</code> is the default.</p>
1641 <p>
1644 Virtual space can be enabled or disabled for rectangular selections or in other circumstances or in both.
1649 <p>
1650 <b id="SCI_SETRECTANGULARSELECTIONMODIFIER">SCI_SETRECTANGULARSELECTIONMODIFIER(int modifier)</b><br />
1652 On GTK+, the key used to indicate that a rectangular selection should be created when combined with a mouse drag can be set.
1653 The three possible values are <code>SCMOD_CTRL</code>=2 (default), <code>SCMOD_ALT</code>=4 or <code>SCMOD_SUPER</code>=8.
1654 Since <code>SCMOD_ALT</code> is often already used by a window manager, the window manager may need configuring to allow this choice.
1655 <code>SCMOD_SUPER</code> is often a system dependent modifier key such as the Left Windows key on a Windows keyboard or the
1656 Command key on a Mac.</p>
1658 <p>
1660 Return the number of selections currently active.</p>
1662 <p>
1666 <p>
1670 <p>
1672 Set a single selection from <code>anchor</code> to <code>caret</code> as the only selection.</p>
1674 <p>
1676 Add a new selection from <code>anchor</code> to <code>caret</code> as the main selection retaining all other
1677 selections as additional selections.
1678 Since there is always at least one selection, to set a list of selections, the first selection should be
1679 added with <code>SCI_SETSELECTION</code> and later selections added with <code>SCI_ADDSELECTION</code></p>
1681 <p>
1683 If there are multiple selections, remove the indicated selection.
1684 If this was the main selection then make the previous selection the main and if it was the first then the last selection becomes main.
1685 If there is only one selection, or there is no selection <code>selection</code>, then there is no effect.</p>
1687 <p>
1690 One of the selections is the main selection which is used to determine what range of text is automatically visible.
1691 The main selection may be displayed in different colours or with a differently styled caret.
1692 Only an already existing selection can be made main.</p>
1694 <p>
1697 <b id="SCI_SETSELECTIONNCARETVIRTUALSPACE">SCI_SETSELECTIONNCARETVIRTUALSPACE(int selection, int space)</b><br />
1698 <b id="SCI_GETSELECTIONNCARETVIRTUALSPACE">SCI_GETSELECTIONNCARETVIRTUALSPACE(int selection)</b><br />
1699 <b id="SCI_SETSELECTIONNANCHOR">SCI_SETSELECTIONNANCHOR(int selection, int posAnchor)</b><br />
1701 <b id="SCI_SETSELECTIONNANCHORVIRTUALSPACE">SCI_SETSELECTIONNANCHORVIRTUALSPACE(int selection, int space)</b><br />
1702 <b id="SCI_GETSELECTIONNANCHORVIRTUALSPACE">SCI_GETSELECTIONNANCHORVIRTUALSPACE(int selection)</b><br />
1703 Set or query the position and amount of virtual space for the caret and anchor of each already existing selection.</p>
1705 <p>
1710 Set or query the start and end position of each already existing selection.
1711 Mostly of use to query each range for its text.</p>
1713 <p>
1716 <b id="SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE(int space)</b><br />
1717 <b id="SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE</b><br />
1718 <b id="SCI_SETRECTANGULARSELECTIONANCHOR">SCI_SETRECTANGULARSELECTIONANCHOR(int posAnchor)</b><br />
1720 <b id="SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE(int space)</b><br />
1721 <b id="SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE">SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE</b><br />
1722 Set or query the position and amount of virtual space for the caret and anchor of the rectangular selection.
1723 After setting the rectangular selection, this is broken down into multiple selections, one for each line.</p>
1725 <p>
1728 <b id="SCI_SETADDITIONALSELFORE">SCI_SETADDITIONALSELFORE(int <a class="jump" href="#colour">colour</a>)</b><br />
1729 <b id="SCI_SETADDITIONALSELBACK">SCI_SETADDITIONALSELBACK(int <a class="jump" href="#colour">colour</a>)</b><br />
1730 Modify the appearance of additional selections so that they can be differentiated from the main selection which has its appearance set with
1739 called with useSelection*Colour value set to true. Subsequent calls to
1743 <p>
1744 <b id="SCI_SETADDITIONALCARETFORE">SCI_SETADDITIONALCARETFORE(int <a class="jump" href="#colour">colour</a>)</b><br />
1746 <b id="SCI_SETADDITIONALCARETSBLINK">SCI_SETADDITIONALCARETSBLINK(bool additionalCaretsBlink)</b><br />
1748 Modify the appearance of additional carets so that they can be differentiated from the main caret which has its appearance set with
1754 <p>
1755 <b id="SCI_SETADDITIONALCARETSVISIBLE">SCI_SETADDITIONALCARETSVISIBLE(bool additionalCaretsVisible)</b><br />
1759 <p>
1762 These commands may be assigned to keys to make it possible to manipulate multiple selections.
1763 <code>SCI_SWAPMAINANCHORCARET</code> moves the caret to the opposite end of the main selection.
1765 </p>
1770 <a class="message" href="#SCI_SCROLLRANGE">SCI_SCROLLRANGE(int secondary, int primary)</a><br />
1772 caretSlop)</a><br />
1774 caretSlop)</a><br />
1776 caretSlop)</a><br />
1785 <a class="message" href="#SCI_SETSCROLLWIDTHTRACKING">SCI_SETSCROLLWIDTHTRACKING(bool tracking)</a><br />
1788 endAtLastLine)</a><br />
1790 </code>
1793 This will attempt to scroll the display by the number of columns and lines that you specify.
1794 Positive line values increase the line number at the top of the screen (i.e. they move the text
1795 upwards as far as the user is concerned), Negative line values do the reverse.</p>
1797 <p>The column measure is the width of a space in the default style. Positive values increase
1798 the column at the left edge of the view (i.e. they move the text leftwards as far as the user
1799 is concerned). Negative values do the reverse.</p>
1804 If the current position (this is the caret if there is no selection) is not visible, the view
1805 is scrolled to make it visible according to the current caret policy.</p>
1808 Scroll the argument positions and the range between them into view giving
1809 priority to the primary position then the secondary position.
1810 The behaviour is similar to <a class="message" href="#SCI_SCROLLCARET"><code>SCI_SCROLLCARET</code></a>
1811 with the primary position used instead of the caret. An effort is then made to ensure that the secondary
1812 position and range between are also visible.
1813 This may be used to make a search match visible.</p>
1823 <tr>
1827 unwanted zone (UZ) where the caret is... unwanted. This zone is defined as a number of
1828 pixels near the vertical margins, and as a number of lines near the horizontal margins.
1829 By keeping the caret away from the edges, it is seen within its context. This makes it
1830 likely that the identifier that the caret is on can be completely seen, and that the
1831 current line is seen with some of the lines following it, which are often dependent on
1832 that line.</td>
1833 </tr>
1835 <tr>
1841 </tr>
1843 <tr>
1846 <td>If set, the display is moved more energetically so the caret can move in the same
1847 direction longer before the policy is applied again. '3UZ' notation is used to indicate
1848 three time the size of the UZ as a distance to the margin.</td>
1849 </tr>
1851 <tr>
1854 <td>If not set, instead of having symmetrical UZs, the left and bottom UZs are extended
1855 up to right and top UZs respectively. This way, we favour the displaying of useful
1856 information: the beginning of lines, where most code reside, and the lines after the
1857 caret, for example, the body of a function.</td>
1858 </tr>
1859 </tbody>
1860 </table>
1864 <tr>
1876 or going into the UZ) display is...</th>
1877 </tr>
1878 </thead>
1881 <tr>
1893 </tr>
1895 <tr>
1907 </tr>
1909 <tr>
1921 </tr>
1923 <tr>
1935 </tr>
1937 <tr>
1949 </tr>
1951 <tr>
1963 </tr>
1965 <tr>
1977 </tr>
1979 <tr>
1991 </tr>
1993 <tr>
2005 </tr>
2007 <tr>
2019 </tr>
2021 <tr>
2033 </tr>
2035 <tr>
2047 </tr>
2049 <tr>
2061 </tr>
2062 </tbody>
2063 </table>
2068 called. It takes <code>VISIBLE_SLOP</code> and <code>VISIBLE_STRICT</code> flags for the policy
2075 The horizontal scroll bar is only displayed if it is needed for the assumed width.
2076 If you never wish to see it, call
2079 when needed.</p>
2084 By default, the vertical scroll bar is always displayed when required. You can choose to hide
2091 view. A value of 0 is the normal position with the first text column visible at the left of the
2092 view.</p>
2098 For performance, Scintilla does not measure the display width of the document to determine
2099 the properties of the horizontal scroll bar. Instead, an assumed width is used.
2100 These messages set and get the document width in pixels assumed by Scintilla.
2101 The default value is 2000.
2102 To ensure the width of the currently visible lines can be scrolled use
2103 <a class="message" href="#SCI_SETSCROLLWIDTHTRACKING"><code>SCI_SETSCROLLWIDTHTRACKING</code></a></p>
2107 If scroll width tracking is enabled then the scroll width is adjusted to ensure that all of the lines currently
2108 displayed can be completely scrolled. This mode never adjusts the scroll width to be narrower.</p>
2114 scrolling one page below the last line.</p>
2120 useWhitespaceForeColour, int colour)</a><br />
2122 useWhitespaceBackColour, int colour)</a><br />
2124 size)</a><br />
2130 </code>
2134 White space can be made visible which may be useful for languages in which white space is
2135 significant, such as Python. Space characters appear as small centred dots and tab characters
2136 as light arrows pointing to the right. There are also ways to control the display of <a
2142 <tr>
2147 <td>The normal display mode with white space displayed as an empty background
2148 colour.</td>
2149 </tr>
2151 <tr>
2157 </tr>
2159 <tr>
2164 <td>White space used for indentation is displayed normally but after the first visible
2165 character, it is shown as dots and arrows.</td>
2166 </tr>
2167 </tbody>
2168 </table>
2176 By default, the colour of visible white space is determined by the lexer in use. The
2177 foreground and/or background colour of all visible white space can be set globally, overriding
2185 </p>
2187 <p>
2192 Text is drawn with the base of each character on a 'baseline'. The height of a line is found from the maximum
2193 that any style extends above the baseline (its 'ascent'), added to the maximum that any style extends below the
2194 baseline (its 'descent').
2197 This may done to make the text easier to read or to accommodate underlines or highlights.
2198 </p>
2204 The cursor is normally chosen in a context sensitive way, so it will be different over the
2205 margin than when over the text. When performing a slow action, you may wish to change to a wait
2207 argument can be:</p>
2211 <tr>
2217 </tr>
2219 <tr>
2224 <td>The wait cursor is displayed when the mouse is over or owned by the Scintilla
2225 window.</td>
2226 </tr>
2227 </tbody>
2228 </table>
2239 When the mouse is pressed inside Scintilla, it is captured so future mouse movement events are
2240 sent to Scintilla. This behaviour may be turned off with
2245 <p>Scintilla can handle the major line end conventions and, depending on settings and
2246 the current lexer also support additional Unicode line ends.</p>
2248 <p>Scintilla can interpret any of the Macintosh (\r), Unix (\n) and Windows (\r\n)
2249 line ends.
2250 When the user presses the Enter key, one of these line
2251 end strings is inserted into the buffer. The default is \r\n in Windows and \n in Unix, but
2257 Next Line (<code>NEL=U+0085</code>), Line Separator (<code>LS=U+2028</code>), and Paragraph Separator (<code>PS=U+2029</code>)
2258 may optionally be interpreted when Unicode line ends is turned on and the current lexer also supports
2259 Unicode line ends.</p>
2268 <a class="message" href="#SCI_SETLINEENDTYPESALLOWED">SCI_SETLINEENDTYPESALLOWED(int lineEndBitSet)</a><br />
2275 presses the Enter key. You can set <code>eolMode</code> to one of <code>SC_EOL_CRLF</code> (0),
2277 message retrieves the current state.</p>
2280 This message changes all the end of line characters in the document to match
2290 returns the current state.</p>
2294 by the current lexer. This is a bit set although there is currently only a single choice
2295 with either <code>SC_LINE_END_TYPE_DEFAULT</code> (0) or <code>SC_LINE_END_TYPE_UNICODE</code> (1).
2296 These values are also used by the other messages concerned with Unicode line ends.</p>
2300 By default, only the ASCII line ends are interpreted. Unicode line ends may be requested with
2302 but this will be ineffective unless the lexer also allows you Unicode line ends.
2307 by Scintilla. It is <code>SCI_GETLINEENDTYPESSUPPORTED & SCI_GETLINEENDTYPESALLOWED</code>.</p>
2311 <p>The styling messages allow you to assign styles to text. If your styling needs can be met by
2312 one of the standard lexers, or if you can write your own, then a lexer is probably the easiest
2313 way to style your document. If you choose to use the container to do the styling you can use
2318 alternative, you might use idle time to style the document. Even if you use a lexer, you might
2319 use the styling commands to mark errors detected by a compiler. The following commands can be
2320 used.</p>
2322 <a class="message" href="#SCI_STARTSTYLING">SCI_STARTSTYLING(int position, int unused)</a><br />
2325 *styles)</a><br />
2329 </code>
2332 Scintilla keeps a record of the last character that is likely to be styled correctly. This is
2333 moved forwards when characters after it are styled and moved backwards if changes are made to
2334 the text of the document before it. Before drawing text, this position is checked to see if any
2338 start styling. Scintilla will always ask to style whole lines.</p>
2342 The unused argument was used in earlier versions but is now ignored.
2343 After
2345 lexical entity to style.</p>
2350 </p>
2356 the next call.</p>
2360 As well as the 8 bits of lexical state stored for each character there is also an integer
2361 stored for each line. This can be used for longer lived parse states such as what the current
2364 Changing the value produces a <a class="message" href="#SC_MOD_CHANGELINESTATE">SC_MOD_CHANGELINESTATE</a> notification.
2365 </p>
2368 This returns the last line that has any line state.</p>
2372 <p>While the style setting messages mentioned above change the style numbers associated with
2373 text, these messages define how those style numbers are interpreted visually. There are 256
2375 There are also some
2377 defined.</p>
2381 <tr>
2386 <td>This style defines the attributes that all styles receive when the
2388 </tr>
2390 <tr>
2395 <td>This style sets the attributes of the text used to display line numbers in a line
2396 number margin. The background colour set for this style also sets the background colour
2397 for all margins that do not have any folding mask bits set. That is, any margin for which
2400 </tr>
2402 <tr>
2411 </tr>
2413 <tr>
2418 <td>This style sets the display attributes used when marking an unmatched brace with the
2420 message.</td>
2421 </tr>
2423 <tr>
2428 <td>This style sets the font used when drawing control characters.
2429 Only the font, size, bold, italics, and character set attributes are used and not
2430 the colour attributes. See
2433 </tr>
2435 <tr>
2440 <td>This style sets the foreground and background colours used when drawing the
2441 indentation guides.</td>
2442 </tr>
2444 <tr>
2451 causes call tips to use this style instead. Only the font face name, font size,
2452 foreground and background colours and character set attributes are used.</td>
2453 </tr>
2455 <tr>
2460 <td>To make it easier for client code to discover the range of styles that are
2461 predefined, this is set to the style number of the last predefined style. This is
2463 for one future predefined style.</td>
2464 </tr>
2466 <tr>
2471 <td>This is not a style but is the number of the maximum style that can be set. Styles
2473 </tr>
2474 </tbody>
2475 </table>
2477 <p>For each style you can set the font name, size and use of bold, italic and underline,
2478 foreground and background colour and the character set. You can also choose to hide text with a
2479 given style, display all characters as upper or lower case and fill from the last character on
2480 a line to the end of the line (for embedded languages). There is also an experimental attribute
2481 to make text read-only.</p>
2483 <p>It is entirely up to you how you use styles. If you want to use syntax colouring you might
2489 *fontName)</a><br />
2490 <a class="message" href="#SCI_STYLEGETFONT">SCI_STYLEGETFONT(int styleNumber, char *fontName)</a><br />
2492 sizeInPoints)</a><br />
2494 <a class="message" href="#SCI_STYLESETSIZEFRACTIONAL">SCI_STYLESETSIZEFRACTIONAL(int styleNumber, int
2495 sizeInHundredthPoints)</a><br />
2496 <a class="message" href="#SCI_STYLEGETSIZEFRACTIONAL">SCI_STYLEGETSIZEFRACTIONAL(int styleNumber)</a><br />
2498 bold)</a><br />
2501 weight)</a><br />
2504 italic)</a><br />
2507 underline)</a><br />
2508 <a class="message" href="#SCI_STYLEGETUNDERLINE">SCI_STYLEGETUNDERLINE(int styleNumber)</a><br />
2510 colour)</a><br />
2513 colour)</a><br />
2516 eolFilled)</a><br />
2517 <a class="message" href="#SCI_STYLEGETEOLFILLED">SCI_STYLEGETEOLFILLED(int styleNumber)</a><br />
2519 int charSet)</a><br />
2520 <a class="message" href="#SCI_STYLEGETCHARACTERSET">SCI_STYLEGETCHARACTERSET(int styleNumber)</a><br />
2522 caseMode)</a><br />
2525 visible)</a><br />
2528 changeable)</a><br />
2529 <a class="message" href="#SCI_STYLEGETCHANGEABLE">SCI_STYLEGETCHANGEABLE(int styleNumber)</a><br />
2531 hotspot)</a><br />
2533 </code>
2537 initialised.</p>
2541 are setting up Scintilla for syntax colouring, it is likely that the lexical styles you set
2542 will be very similar. One way to set the styles is to:<br />
2551 <b id="SCI_STYLESETSIZEFRACTIONAL">SCI_STYLESETSIZEFRACTIONAL(int styleNumber, int sizeInHundredthPoints)</b><br />
2561 attributes that are used to match the fonts you request to those available. The
2563 only the first 32 characters of the name are used and the name is not case sensitive. For
2564 internal caching, Scintilla tracks fonts by name and does care about the casing of font names,
2565 so please be consistent. On GTK+, Pango is used to display text.</p>
2567 or to a fractional point size in hundredths of a point with <code>SCI_STYLESETSIZEFRACTIONAL</code>
2569 For example, a text size of 9.4 points is set with <code>SCI_STYLESETSIZEFRACTIONAL(<style>, 940)</code>.
2570 </p>
2572 or <code>SCI_STYLESETWEIGHT</code>. The weight is a number between 1 and 999 with 1 being very light
2573 and 999 very heavy. While any value can be used, fonts often only support between 2 and 4 weights with three weights
2574 being common enough to have symbolic names:
2578 The <code>SCI_STYLESETBOLD</code> message takes a boolean argument with 0 choosing <code>SC_WEIGHT_NORMAL</code>
2580 </p>
2583 underline)</b><br />
2585 You can set a style to be underlined. The underline is drawn in the foreground colour. All
2586 characters with a style that includes the underline attribute are underlined, even if they are
2587 white space.</p>
2595 Text is drawn in the foreground colour. The space in each character cell that is not occupied
2596 by the character is drawn in the background colour.</p>
2599 eolFilled)</b><br />
2601 If the last character in the line has a style with this attribute set, the remainder of the
2602 line up to the right edge of the window is filled with the background colour set for the last
2603 character. This is useful when a document contains embedded sections in another language such
2605 and a consistent background colour (different from the background colour set for the HTML
2606 styles) to all JavaScript styles then JavaScript sections will be easily distinguished from
2607 HTML.</p>
2610 charSet)</b><br />
2612 You can set a style to use a different character set than the default. The places where such
2613 characters sets are likely to be useful are comments and literal strings. For example,
2615 strings in Russian would display correctly in C and C++ (<code>SCE_C_STRING</code> is the style
2616 number used by the C and C++ lexer to display literal strings; it has the value 6). This
2617 feature works differently on Windows and GTK+.</p>
2626 <code>SC_CHARSET_SHIFTJIS</code>, <code>SC_CHARSET_SYMBOL</code>, <code>SC_CHARSET_THAI</code>,
2638 The value of caseMode determines how text is displayed. You can set upper case
2641 displayed.</p>
2645 Text is normally visible. However, you can completely hide it by giving it a style with the
2647 hypertext keywords in HTML or XML.</p>
2650 changeable)</b><br />
2652 This is an experimental and incompletely implemented style attribute. The default setting is
2654 read-only. Currently it only stops the caret from being within not-changeable text and does not
2655 yet stop deleting a range that contains not-changeable text.</p>
2658 hotspot)</b><br />
2660 This style is used to mark ranges of text that can detect mouse clicks.
2661 The cursor changes to a hand over hotspots, and the foreground, and background colours
2662 may change and an underline appear to indicate that these areas are sensitive to clicking.
2663 This may be used to allow hyperlinks to other documents.</p>
2667 <p>The selection is shown by changing the foreground and/or background colours. If one of these
2668 is not set then that attribute is not changed for the selection. The default is to show the
2669 selection by changing the background to light grey and leaving the foreground the same as when
2670 it was not selected. When there is no selection, the current insertion point is marked by the
2671 text caret. This is a vertical line that is normally blinking on and off to attract the users
2672 attention.</p>
2673 <code><a class="message" href="#SCI_SETSELFORE">SCI_SETSELFORE(bool useSelectionForeColour, int colour)</a><br />
2674 <a class="message" href="#SCI_SETSELBACK">SCI_SETSELBACK(bool useSelectionBackColour, int colour)</a><br />
2681 <a class="message" href="#SCI_SETCARETLINEVISIBLE">SCI_SETCARETLINEVISIBLE(bool show)</a><br />
2685 <a class="message" href="#SCI_SETCARETLINEBACKALPHA">SCI_SETCARETLINEBACKALPHA(int alpha)</a><br />
2687 <a class="message" href="#SCI_SETCARETLINEVISIBLEALWAYS">SCI_SETCARETLINEVISIBLEALWAYS(bool alwaysVisible)</a><br />
2688 <a class="message" href="#SCI_GETCARETLINEVISIBLEALWAYS">SCI_GETCARETLINEVISIBLEALWAYS</a><br />
2695 <a class="message" href="#SCI_SETHOTSPOTACTIVEFORE">SCI_SETHOTSPOTACTIVEFORE(bool useSetting, int colour)</a><br />
2697 <a class="message" href="#SCI_SETHOTSPOTACTIVEBACK">SCI_SETHOTSPOTACTIVEBACK(bool useSetting, int colour)</a><br />
2699 <a class="message" href="#SCI_SETHOTSPOTACTIVEUNDERLINE">SCI_SETHOTSPOTACTIVEUNDERLINE(bool underline)</a><br />
2700 <a class="message" href="#SCI_GETHOTSPOTACTIVEUNDERLINE">SCI_GETHOTSPOTACTIVEUNDERLINE</a><br />
2701 <a class="message" href="#SCI_SETHOTSPOTSINGLELINE">SCI_SETHOTSPOTSINGLELINE(bool singleLine)</a><br />
2703 <a class="message" href="#SCI_SETCARETSTICKY">SCI_SETCARETSTICKY(int useCaretStickyBehaviour)</a><br />
2706 </code>
2712 You can choose to override the default selection colouring with these two messages. The colour
2715 argument has no effect.</p>
2716 <p><b id="SCI_SETSELALPHA">SCI_SETSELALPHA(int <a class="jump" href="#alpha">alpha</a>)</b><br />
2718 The selection can be drawn translucently in the selection background colour by
2719 setting an alpha value.</p>
2723 The selection can be drawn up to the right hand border by setting this property.</p>
2736 <b id="SCI_SETCARETLINEBACKALPHA">SCI_SETCARETLINEBACKALPHA(int <a class="jump" href="#alpha">alpha</a>)</b><br />
2738 You can choose to make the background colour of the line containing the caret different with
2739 these messages. To do this, set the desired background colour with
2743 background colouring has highest priority when a line has markers that would otherwise change
2744 the background colour.
2745 The caret line may also be drawn translucently which allows other background colours to show
2746 through. This is done by setting the alpha (translucency) value by calling
2747 SCI_SETCARETLINEBACKALPHA. When the alpha is not SC_ALPHA_NOALPHA,
2748 the caret line is drawn after all other features so will affect the colour of all other features.
2749 </p>
2751 <p><b id="SCI_SETCARETLINEVISIBLEALWAYS">SCI_SETCARETLINEVISIBLEALWAYS(bool alwaysVisible)</b><br />
2753 Choose to make the caret line always visible even when the window is not in focus.
2754 Default behaviour <code>SCI_SETCARETLINEVISIBLEALWAYS(false)</code> the caret line is only visible when the window is in focus.
2755 </p>
2760 determines the time in milliseconds that the caret is visible or invisible before changing
2761 state. Setting the period to 0 stops the caret blinking. The default value is 500 milliseconds.
2771 <p>The block character draws most combining and multibyte character sequences successfully,
2772 though some fonts like Thai Fonts (and possibly others) can sometimes appear strange when
2773 the cursor is positioned at these characters, which may result in only drawing a part of the
2774 cursor character sequence. This is most notable on Windows platforms.</p>
2781 1.50), similar to setting the caret style to CARETSTYLE_INVISIBLE (though not interchangeable).
2782 This setting only affects the width of the cursor when the cursor style is set to line caret
2783 mode, it does not affect the width for a block caret.</p>
2785 <p><b id="SCI_SETHOTSPOTACTIVEFORE">SCI_SETHOTSPOTACTIVEFORE(bool useHotSpotForeColour, int <a class="jump"
2788 <b id="SCI_SETHOTSPOTACTIVEBACK">SCI_SETHOTSPOTACTIVEBACK(bool useHotSpotBackColour, int <a class="jump"
2795 While the cursor hovers over text in a style with the hotspot attribute set,
2796 the default colouring can be modified and an underline drawn with these settings.
2797 Single line mode stops a hotspot from wrapping onto next line.</p>
2802 These messages set, get or toggle the caretSticky setting which controls when the last position
2803 of the caret on the line is saved.</p>
2806 (and all caret position changes) will remember the
2807 caret's new horizontal position when moving to different lines. This is the default.</p>
2809 <p>When set to <code>SC_CARETSTICKY_ON</code> (1), the sticky flag is on, and the only thing which will cause the editor to remember the
2810 horizontal caret position is moving the caret with mouse or keyboard (left/right arrow keys, home/end keys, etc). </p>
2812 <p>When set to <code>SC_CARETSTICKY_WHITESPACE</code> (2), the caret acts like mode 0 (sticky off) except under one
2813 special case; when space or tab characters are inserted. (Including pasting <b>only space/tabs</b> -- undo, redo,
2814 etc. do not exhibit this behaviour..).</p>
2816 <p><code>SCI_TOGGLECARETSTICKY</code> switches from <code>SC_CARETSTICKY_ON</code> and <code>SC_CARETSTICKY_WHITESPACE</code>
2817 to <code>SC_CARETSTICKY_OFF</code> and from <code>SC_CARETSTICKY_OFF</code> to <code>SC_CARETSTICKY_ON</code>.</p>
2821 <p>Some characters, such as control characters and invalid bytes, do not have a visual glyph or use a glyph that is hard to distinguish.</p>
2823 <p>Control characters (characters with codes less than 32, or between 128 and 159 in some encodings)
2824 are displayed by Scintilla using their mnemonics inverted in a rounded rectangle. These mnemonics come from the
2825 early days of signalling, though some are still used (LF = Line Feed, BS = Back Space, CR =
2826 Carriage Return, for example).</p>
2832 <p>For the high 'C1' values:
2838 <p>Invalid bytes are shown in a similar way with an 'x' followed by their value in hexadecimal, like "xFE".</p>
2840 <code>
2841 <a class="message" href="#SCI_SETREPRESENTATION">SCI_SETREPRESENTATION(const char *encodedCharacter, const char *representation)</a><br />
2842 <a class="message" href="#SCI_GETREPRESENTATION">SCI_GETREPRESENTATION(const char *encodedCharacter, char *representation)</a><br />
2843 <a class="message" href="#SCI_CLEARREPRESENTATION">SCI_CLEARREPRESENTATION(const char *encodedCharacter)</a><br />
2844 <a class="message" href="#SCI_SETCONTROLCHARSYMBOL">SCI_SETCONTROLCHARSYMBOL(int symbol)</a><br />
2846 </code>
2848 <p><b id="SCI_SETREPRESENTATION">SCI_SETREPRESENTATION(const char *encodedCharacter, const char *representation)</b><br />
2849 <b id="SCI_GETREPRESENTATION">SCI_GETREPRESENTATION(const char *encodedCharacter, char *representation)</b><br />
2850 <b id="SCI_CLEARREPRESENTATION">SCI_CLEARREPRESENTATION(const char *encodedCharacter)</b><br />
2851 Any character, including those normally displayed as mnemonics may be represented by a
2852 string inverted in a rounded rectangle.</p>
2854 <p>For example, the Ohm sign Ω U+2126 looks very similar to the Greek Omega character Ω U+03C9 so,
2855 for the UTF-8 encoding, to distinguish the Ohm sign as "U+2126 Ω" this call could be made:
2858 <p>The encodedCharacter parameter is a NUL-terminated string of the bytes for one character in the
2859 current encoding. This can not be used to set a representation for multiple-character strings. </p>
2861 <p>The NUL (0) character is a special case since the encodedCharacter parameter is NUL terminated, the NUL
2862 character is specified as an empty string.</p>
2866 The mnemonics may be replaced by a nominated symbol with an ASCII code in the
2868 as mnemonics. The symbol you set is rendered in the font of the style set for the character.
2875 to the left of the text display, plus a gap either side of
2876 the text. Each margin can be set to display only symbols, line numbers, or text with <a
2878 Textual margins may also display symbols.
2879 The markers
2881 href="#SCI_SETMARGINMASKN"><code>SCI_SETMARGINMASKN</code></a>. Any markers not associated with
2882 a visible margin will be displayed as changes in background colour in the text. A width in
2883 pixels can be set for each margin. Margins with a zero width are ignored completely. You can
2886 selects a line of text.</p>
2890 is hidden. Margin 1 is set to display non-folding symbols and is given a width of 16 pixels, so
2891 it is visible. Margin 2 is set to display the folding symbols, but is given a width of 0, so it
2892 is hidden. Of course, you can set the margins to be whatever you wish.</p>
2895 <p><img src="styledmargin.png" alt="Styled text margins used to show revision and blame information" /></p>
2898 type)</a><br />
2901 pixelWidth)</a><br />
2904 mask)</a><br />
2907 sensitive)</a><br />
2909 margin)</a><br />
2911 cursor)</a><br />
2913 margin)</a><br />
2915 pixels)</a><br />
2918 pixels)</a><br />
2920 <a class="message" href="#SCI_SETFOLDMARGINCOLOUR">SCI_SETFOLDMARGINCOLOUR(bool useSetting, int colour)</a><br />
2921 <a class="message" href="#SCI_SETFOLDMARGINHICOLOUR">SCI_SETFOLDMARGINHICOLOUR(bool useSetting, int colour)</a><br />
2924 <a class="message" href="#SCI_MARGINSETSTYLE">SCI_MARGINSETSTYLE(int line, int style)</a><br />
2926 <a class="message" href="#SCI_MARGINSETSTYLES">SCI_MARGINSETSTYLES(int line, char *styles)</a><br />
2927 <a class="message" href="#SCI_MARGINGETSTYLES">SCI_MARGINGETSTYLES(int line, char *styles)</a><br />
2929 <a class="message" href="#SCI_MARGINSETSTYLEOFFSET">SCI_MARGINSETSTYLEOFFSET(int style)</a><br />
2931 <a class="message" href="#SCI_SETMARGINOPTIONS">SCI_SETMARGINOPTIONS(int marginOptions)</a><br />
2933 </code>
2937 These two routines set and get the type of a margin. The margin argument should be 0, 1, 2, 3 or 4.
2942 By convention, margin 0 is used for line numbers and the next two are used for symbols. You can
2944 symbol margins that set their background colour to match the STYLE_DEFAULT background and
2945 foreground colours.</p>
2949 These routines set and get the width of a margin in pixels. A margin with zero width is
2951 is a reasonable guess if you are not sure what would be appropriate. Line number margins widths
2952 should take into account the number of lines in the document and the line number style. You
2955 suitable width.</p>
2960 displayed in a margin that is enabled for symbols. There is a useful constant,
2962 symbols used to denote folding. You can assign a wide range of symbols and colours to each of
2963 the 32 logical symbols, see <a href="#Markers">Markers</a> for more information. If <code>(mask
2969 does not appear in the mask of any margin with a non-zero width, the marker changes the
2970 background colour of the line. For example, suppose you decide to use logical marker 10 to mark
2971 lines with a syntax error and you want to show such lines by changing the background colour.
2973 sure that no symbol margin includes 0x400 in its mask, any line with the marker gets the
2974 background colour changed.</p>
2977 which is the default set by Scintilla.
2980 decimal. Of course, you may need to display all 32 symbols in a margin, in which case use
2984 sensitive)</b><br />
2986 Each of the five margins can be set sensitive or insensitive to mouse clicks. A click in a
2990 selection margins which make it easy to select ranges of lines. By default, all margins are
2991 insensitive.</p>
2994 cursor)</b><br />
2996 A reversed arrow cursor is normally shown over all margins. This may be changed to a normal arrow with
2998 reversed arrow with
3005 These messages set and get the width of the blank margin on both sides of the text in pixels.
3006 The default is to one pixel on each side.</p>
3008 <p><b id="SCI_SETFOLDMARGINCOLOUR">SCI_SETFOLDMARGINCOLOUR(bool useSetting, int colour)</b><br />
3009 <b id="SCI_SETFOLDMARGINHICOLOUR">SCI_SETFOLDMARGINHICOLOUR(bool useSetting, int colour)</b><br />
3010 These messages allow changing the colour of the fold margin and fold margin highlight.
3011 On Windows the fold margin colour defaults to ::GetSysColor(COLOR_3DFACE) and the fold margin highlight
3012 colour to ::GetSysColor(COLOR_3DHIGHLIGHT).</p>
3014 <p>
3022 Text margins are created with the type SC_MARGIN_TEXT or SC_MARGIN_RTEXT.
3024 The whole of the text margin on a line may be displayed in a particular style with
3028 Setting a text margin will cause a
3030 notification to be sent.
3031 </p>
3032 <p>
3033 Only some style attributes are active in text margins: font, size/sizeFractional, bold/weight, italics, fore, back, and characterSet.
3034 </p>
3035 <p>
3038 Margin styles may be completely separated from standard text styles by setting a style offset. For example,
3040 256 up to 511 so they do not overlap styles set by lexers. Each style number set with <code>SCI_MARGINSETSTYLE</code>
3042 </p>
3043 <p>
3044 Always call <a class="message" href="#SCI_ALLOCATEEXTENDEDSTYLES">SCI_ALLOCATEEXTENDEDSTYLES</a>
3045 before <code>SCI_MARGINSETSTYLEOFFSET</code> and use the result as the argument to <code>SCI_MARGINSETSTYLEOFFSET</code>.
3046 </p>
3047 <p>
3050 Define margin options by enabling appropriate bit flags. At the moment, only one flag is available
3051 <code>SC_MARGINOPTION_SUBLINESELECT</code>=1, which controls how wrapped lines are selected when clicking
3052 on margin in front of them. If <code>SC_MARGINOPTION_SUBLINESELECT</code> is set only sub line of wrapped
3053 line is selected, otherwise whole wrapped line is selected. Margin options are set to
3055 </p>
3059 <p>Annotations are read-only lines of text underneath each line of editable text.
3060 An annotation may consist of multiple lines separated by '\n'.
3061 Annotations can be used to display an assembler version of code for debugging or to show diagnostic messages inline or to
3062 line up different versions of text in a merge tool.</p>
3063 <p>Annotations count as display lines for the methods
3069 <code>
3070 <a class="message" href="#SCI_ANNOTATIONSETTEXT">SCI_ANNOTATIONSETTEXT(int line, char *text)</a><br />
3071 <a class="message" href="#SCI_ANNOTATIONGETTEXT">SCI_ANNOTATIONGETTEXT(int line, char *text)</a><br />
3072 <a class="message" href="#SCI_ANNOTATIONSETSTYLE">SCI_ANNOTATIONSETSTYLE(int line, int style)</a><br />
3074 <a class="message" href="#SCI_ANNOTATIONSETSTYLES">SCI_ANNOTATIONSETSTYLES(int line, char *styles)</a><br />
3075 <a class="message" href="#SCI_ANNOTATIONGETSTYLES">SCI_ANNOTATIONGETSTYLES(int line, char *styles)</a><br />
3078 <a class="message" href="#SCI_ANNOTATIONSETVISIBLE">SCI_ANNOTATIONSETVISIBLE(int visible)</a><br />
3080 <a class="message" href="#SCI_ANNOTATIONSETSTYLEOFFSET">SCI_ANNOTATIONSETSTYLEOFFSET(int style)</a><br />
3082 </code>
3084 <p>
3095 The whole of the text ANNOTATION on a line may be displayed in a particular style with
3097 <code>SCI_ANNOTATIONSETSTYLES</code> which uses an array of bytes with each byte setting the style
3098 of the corresponding text byte similar to <code>SCI_SETSTYLINGEX</code>. The text must be set first as it
3099 specifies how long the annotation is so how many bytes of styling to read.
3100 Setting an annotation will cause a
3102 notification to be sent.
3103 </p>
3104 <p>
3105 The number of lines annotating a line can be retrieved with <code>SCI_ANNOTATIONGETLINES</code>.
3107 which is equivalent to clearing each line (setting to 0) and then deleting other memory used for this feature.
3108 </p>
3109 <p>
3110 Only some style attributes are active in annotations: font, size/sizeFractional, bold/weight, italics, fore, back, and characterSet.
3111 </p>
3112 <p>
3115 Annotations can be made visible in a view and there is a choice of display style when visible.
3117 argument can be one of:</p>
3121 <tr>
3127 </tr>
3129 <tr>
3135 </tr>
3137 <tr>
3143 </tr>
3144 </tbody>
3145 </table>
3147 <p>
3150 Annotation styles may be completely separated from standard text styles by setting a style offset. For example,
3151 <code>SCI_ANNOTATIONSETSTYLEOFFSET(512)</code> would allow the annotation styles to be numbered from
3152 512 up to 767 so they do not overlap styles set by lexers (or margins if margins offset is 256).
3155 </p>
3156 <p>
3157 Always call <a class="message" href="#SCI_ALLOCATEEXTENDEDSTYLES">SCI_ALLOCATEEXTENDEDSTYLES</a>
3158 before <code>SCI_ANNOTATIONSETSTYLEOFFSET</code> and use the result as the argument to <code>SCI_ANNOTATIONSETSTYLEOFFSET</code>.
3159 </p>
3174 <a class="message" href="#SCI_SETIMEINTERACTION">SCI_SETIMEINTERACTION(int imeInteraction)</a><br />
3178 <a class="message" href="#SCI_SETWORDCHARS">SCI_SETWORDCHARS(<unused>, const char *characters)</a><br />
3179 <a class="message" href="#SCI_GETWORDCHARS">SCI_GETWORDCHARS(<unused>, char *characters)</a><br />
3180 <a class="message" href="#SCI_SETWHITESPACECHARS">SCI_SETWHITESPACECHARS(<unused>, const char *characters)</a><br />
3181 <a class="message" href="#SCI_GETWHITESPACECHARS">SCI_GETWHITESPACECHARS(<unused>, char *characters)</a><br />
3182 <a class="message" href="#SCI_SETPUNCTUATIONCHARS">SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)</a><br />
3183 <a class="message" href="#SCI_GETPUNCTUATIONCHARS">SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)</a><br />
3188 </code>
3192 the handle to the Scintilla window you created as your editor.</p>
3194 <p>While we are on the subject of forwarding messages in Windows, the top level window should
3196 collect changes to mouse settings, but could be used for other user interface items in the
3197 future).</p>
3201 These messages turn buffered drawing on or off and report the buffered drawing state. Buffered
3202 drawing draws each line into a bitmap rather than directly to the screen and then copies the
3203 bitmap to the screen. This avoids flickering although it does take longer. The default is for
3204 drawing to be buffered.</p>
3208 There are several orders in which the text area may be drawn offering a trade-off between speed
3209 and allowing all pixels of text to be seen even when they overlap other elements.</p>
3211 run of characters in one style is drawn along with its background.
3212 If a character overhangs the end of a run, such as in "<i>V</i>_" where the
3215 cuts it off.</p>
3217 fixes this by drawing all the backgrounds of a line first and then drawing the text
3218 in transparent mode. Lines are drawn separately and no line will overlap another
3219 so any pixels that overlap into another line such as extreme ascenders and
3220 descenders on characters will be cut off.
3221 Two phase drawing may flicker more than single phase
3222 unless buffered drawing is on or the platform is naturally buffered.
3223 The default is for drawing to be two phase.</p>
3225 draws the whole area multiple times, once for each feature, building up the
3226 the appearance in layers or phases. The coloured backgrounds for all lines are
3227 drawn before any text and then all the text is drawn in transparent mode over this
3228 combined background without clipping text to the line boundaries. This allows
3229 extreme ascenders and decenders to overflow into the adjacent lines.
3231 if buffered drawing is turned on.
3232 Multiple phase drawing is slower than two phase drawing.
3234 or higher can ensure that multiple phase drawing is not significantly slower.</p>
3238 This property has been replaced with the preceding PHASESDRAW property which is more general,
3239 allowing multiple phase drawing as well as one and two phase drawing.</p>
3243 The technology property allows choosing between different drawing APIs and options.
3247 can be chosen to use the Direct2D and DirectWrite APIs for higher quality antialiased drawing.
3250 is retained after being presented which may prevent drawing failures on some cards and drivers.
3251 Since Direct2D buffers drawing, Scintilla's buffering can be turned off with
3254 is provisional, it may be changed or removed in a future release if a better solution is found.</span></p>
3258 Manage font quality (antialiasing method). Currently, the following values are available on Windows:
3263 <p>In case it is necessary to squeeze more options into this property, only a limited number of bits defined
3268 Scintilla has some support for Japanese, Chinese and Korean DBCS. Use this message with
3269 <code>codePage</code> set to the code page number to set Scintilla to use code page information
3270 to ensure double byte characters are treated as one character rather than two. This also stops
3271 the caret from moving between the two bytes in a double byte character.
3272 Do not use this message to choose between different single byte character sets: it doesn't do that.
3273 Call with
3277 <p>Code page <code>SC_CP_UTF8</code> (65001) sets Scintilla into Unicode mode with the document
3278 treated as a sequence of characters expressed in UTF-8. The text is converted to the platform's
3279 normal Unicode encoding before being drawn by the OS and thus can display Hebrew, Arabic,
3280 Cyrillic, and Han characters. Languages which can use two characters stacked vertically in one
3281 horizontal space, such as Thai, will mostly work but there are some issues where the characters
3282 are drawn separately leading to visual glitches. Bi-directional text is not supported. </p>
3286 although these may require installation of language specific support.</p>
3290 When entering text in Chinese, Japanese, or Korean an Input Method Editor (IME) may be displayed.
3291 The IME may be an extra window appearing above Scintilla or may be displayed by Scintilla itself
3292 as text. On some platforms there is a choice between the two techniques.
3294 behaviour to the IME in other applications.
3295 An inline IME <code>SC_IME_INLINE</code> (1) may work better with some Scintilla features such as
3296 rectangular and multiple selection.</p>
3297 <p>The windowed behaviour can be chosen with <code>SCI_SETIMEINTERACTION(SC_IME_WINDOWED)</code>
3299 Scintilla may ignore this call in some cases. For example, the inline behaviour might only be supported for some languages.</p>
3303 On Windows, character keys are normally handled differently depending on whether Scintilla is a wide
3304 or narrow character window with character messages treated as Unicode when wide and as 8 bit otherwise.
3305 Set this property to always treat as Unicode. This option is needed for Delphi.</p>
3308 Scintilla has several functions that operate on words, which are defined to be contiguous
3309 sequences of characters from a particular set of characters. This message defines which
3310 characters are members of that set. The character sets are set to default values before processing this
3311 function.
3312 For example, if you don't allow '_' in your set of characters
3313 use:<br />
3314 <code>SCI_SETWORDCHARS(0, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789")</code>;</p>
3317 This fills the characters parameter with all the characters included in words.
3318 The characters parameter must be large enough to hold all of the characters.
3319 If the characters parameter is 0 then the length that should be allocated
3320 to store the entire set is returned.</p>
3322 <p><b id="SCI_SETWHITESPACECHARS">SCI_SETWHITESPACECHARS(<unused>, const char *characters)</b><br />
3323 <b id="SCI_GETWHITESPACECHARS">SCI_GETWHITESPACECHARS(<unused>, char *characters)</b><br />
3324 Similar to <code>SCI_SETWORDCHARS</code>, this message allows the user to define which chars Scintilla considers
3325 as whitespace. Setting the whitespace chars allows the user to fine-tune Scintilla's behaviour doing
3326 such things as moving the cursor to the start or end of a word; for example, by defining punctuation chars
3327 as whitespace, they will be skipped over when the user presses ctrl+left or ctrl+right.
3329 reset the whitespace characters to the default set.
3332 <p><b id="SCI_SETPUNCTUATIONCHARS">SCI_SETPUNCTUATIONCHARS(<unused>, const char *characters)</b><br />
3333 <b id="SCI_GETPUNCTUATIONCHARS">SCI_GETPUNCTUATIONCHARS(<unused>, char *characters)</b><br />
3335 allows the user to define which chars Scintilla considers as punctuation.
3339 Use the default sets of word and whitespace characters. This sets whitespace to space, tab and other
3340 characters with codes less than 0x20, with word characters set to alphanumeric and '_'.
3341 </p>
3347 Scintilla can be told to grab the focus with this message. This is needed more on GTK+ where
3348 focus handling is more complicated than on Windows.</p>
3351 that have complex focus requirements such as having their own window that gets the real focus
3352 but with the need to indicate that Scintilla has the logical focus.</p>
3356 pos2)</a><br />
3358 <a class="message" href="#SCI_BRACEHIGHLIGHTINDICATOR">SCI_BRACEHIGHLIGHTINDICATOR(bool useBraceHighlightIndicator, int indicatorNumber)</a><br />
3359 <a class="message" href="#SCI_BRACEBADLIGHTINDICATOR">SCI_BRACEBADLIGHTINDICATOR(bool useBraceBadLightIndicator, int indicatorNumber)</a><br />
3361 maxReStyle)</a><br />
3362 </code>
3365 Up to two characters can be highlighted in a 'brace highlighting style', which is defined as
3366 style number <a class="message" href="#StyleDefinition"><code>STYLE_BRACELIGHT</code></a> (34).
3367 If you have enabled indent guides, you may also wish to highlight the indent that corresponds
3376 highlight.</p>
3378 <p><b id="SCI_BRACEHIGHLIGHTINDICATOR">SCI_BRACEHIGHLIGHTINDICATOR(bool useBraceHighlightIndicator, int indicatorNumber)</b><br />
3379 Use specified indicator to highlight matching braces instead of changing their style.</p>
3381 <p><b id="SCI_BRACEBADLIGHTINDICATOR">SCI_BRACEBADLIGHTINDICATOR(bool useBraceBadLightIndicator, int indicatorNumber)</b><br />
3382 Use specified indicator to highlight non matching brace instead of changing its style.</p>
3388 from a closing brace. If the character at position is not a brace character, or a matching
3389 brace cannot be found, the return value is -1. Otherwise, the return value is the position of
3390 the matching brace.</p>
3392 <p>A match only occurs if the style of the matching brace is the same as the starting brace or
3393 the matching brace is beyond the end of styling. Nested braces are handled correctly. The
3395 the length of brace searches.</p>
3399 <p>Indentation (the white space at the start of a line) is often used by programmers to clarify
3400 program structure and in some languages, for example Python, it may be part of the language
3401 syntax. Tabs are normally used in editors to insert a tab character or to pad text with spaces
3402 up to the next tab.</p>
3404 <p>When Scintilla is laying out a section of text, text after a tab character will usually be
3405 displayed at the next multiple of TABWIDTH columns from the left. However, it is also possible
3406 to explicitly set tabstops in pixels for each line.</p>
3408 <p>Scintilla can be set to treat tab and backspace in the white space at the start of a line in
3409 a special way: inserting a tab indents the line to the next indent position rather than just
3410 inserting a tab at the current character position and backspace unindents the line rather than
3411 deleting a character. Scintilla can also display indentation guides (vertical lines) to help
3412 you to generate code.</p>
3425 bsUnIndents)</a><br />
3428 indentation)</a><br />
3431 line)</a><br />
3432 <a class="message" href="#SCI_SETINDENTATIONGUIDES">SCI_SETINDENTATIONGUIDES(int indentView)</a><br />
3436 </code>
3448 adds an explicit tabstop at the specified distance from the left (in pixels), and
3449 <code>SCI_GETNEXTTABSTOP</code> gets the next explicit tabstop position set after the given x position,
3450 or zero if there aren't any.
3451 Changing tab stops produces a <a class="message" href="#SC_MOD_CHANGETABSTOPS">SC_MOD_CHANGETABSTOPS</a> notification.
3452 </p>
3457 of tabs and spaces or be based purely on spaces. Set <code>useTabs</code> to <code>false</code>
3458 (0) to create all tabs and indents out of spaces. The default is <code>true</code>. You can use
3460 position taking the width of a tab into account.</p>
3465 0, the indent size is the same as the tab size. There are no limits on indent sizes, but values
3466 less than 0 or large values may have undesirable effects.
3467 </p>
3473 </p>
3475 <p>Inside indentation white space, the tab and backspace keys can be made to indent and
3476 unindent rather than insert a tab character or delete a character with the
3481 The amount of indentation on a line can be discovered and set with
3482 <code>SCI_GETLINEINDENTATION</code> and <code>SCI_SETLINEINDENTATION</code>. The indentation is
3483 measured in character columns, which correspond to the width of space characters.</p>
3486 This returns the position at the end of indentation of a line.</p>
3490 Indentation guides are dotted vertical lines that appear within indentation white space every
3491 indent size columns. They make it easy to see which constructs line up especially when they
3494 foreground and background colour of the indentation guides.</p>
3497 SC_IV_NONE turns the feature off but the other 3 states determine how far the guides appear on
3498 empty lines. </p>
3500 <tbody>
3501 <tr>
3504 </tr>
3506 <tr>
3509 </tr>
3511 <tr>
3513 <td>Indentation guides are shown beyond the actual indentation up to the level of the
3514 next non-empty line.
3515 If the previous non-empty line was a fold header then indentation guides are shown for
3516 one more level of indent than that line. This setting is good for Python.</td>
3517 </tr>
3519 <tr>
3521 <td>Indentation guides are shown beyond the actual indentation up to the level of the
3522 next non-empty line or previous non-empty line whichever is the greater.
3523 This setting is good for most languages.</td>
3524 </tr>
3526 </tbody>
3527 </table>
3531 When brace highlighting occurs, the indentation guide corresponding to the braces may be
3533 href="#StyleDefinition"><code>STYLE_BRACELIGHT</code></a> (34). Set <code>column</code> to 0 to
3534 cancel this highlight.</p>
3538 <p>There are 32 markers, numbered 0 to <code>MARKER_MAX</code> (31), and you can assign any combination of them to each
3540 margin</a> to the left of the text. If the selection margin is set to zero width, the
3546 or the current point of execution, break points, or whatever you need marking. If you do not
3549 <p>Each marker number has a symbol associated with it. You can also set the foreground and
3550 background colour for each marker number, so you can use the same symbol more than once with
3551 different colouring for different uses. Scintilla has a set of symbols you can assign
3555 <p>The markers are drawn in the order of their numbers, so higher numbered markers appear on
3556 top of lower numbered ones. Markers try to move with their text by tracking where the start of
3558 operation, with the markers of the next line.</p>
3560 markerSymbols)</a><br />
3562 const char *xpm)</a><br />
3565 <a class="message" href="#SCI_RGBAIMAGESETSCALE">SCI_RGBAIMAGESETSCALE(int scalePercent)</a><br />
3566 <a class="message" href="#SCI_MARKERDEFINERGBAIMAGE">SCI_MARKERDEFINERGBAIMAGE(int markerNumber,
3567 const char *pixels)</a><br />
3569 </a><br />
3571 colour)</a><br />
3573 colour)</a><br />
3574 <a class="message" href="#SCI_MARKERSETBACKSELECTED">SCI_MARKERSETBACKSELECTED(int markerNumber, int
3575 colour)</a><br />
3576 <a class="message" href="#SCI_MARKERENABLEHIGHLIGHT">SCI_MARKERENABLEHIGHLIGHT(int enabled)</a><br />
3578 alpha)</a><br />
3580 <a class="message" href="#SCI_MARKERADDSET">SCI_MARKERADDSET(int line, int markerMask)</a><br />
3582 markerNumber)</a><br />
3586 markerMask)</a><br />
3588 markerMask)</a><br />
3590 handle)</a><br />
3592 </code>
3596 an ASCII character. The general-purpose marker symbols currently available are:<br />
3613 </p>
3616 The <code>SC_MARK_FULLRECT</code> symbol mirrors this, changing only the margin background colour.
3619 of lines. You would also use it if you changed the folding style and wanted one or more of the
3623 plugins may allocate that marker number.
3624 </p>
3626 <p>There are also marker symbols designed for use in the folding margin in a flattened tree
3627 style.<br />
3641 Characters can be used as markers by adding the ASCII value of the character to
3646 <p>The marker numbers <code>SC_MARKNUM_FOLDER</code> and <code>SC_MARKNUM_FOLDEROPEN</code> are
3647 used for showing that a fold is present and open or closed. Any symbols may be assigned for
3650 these two, more assignments are needed for the flattened tree style:
3659 Macintosh), plus/minus shows folded lines as '+' and opened folds as '-', Circle tree, Box
3660 tree.</p>
3664 <tr>
3674 </tr>
3675 </thead>
3678 <tr>
3688 </tr>
3690 <tr>
3700 </tr>
3702 <tr>
3712 </tr>
3714 <tr>
3724 </tr>
3726 <tr>
3736 </tr>
3738 <tr>
3748 </tr>
3750 <tr>
3760 </tr>
3761 </tbody>
3762 </table>
3766 *xpm)</b><br />
3767 Markers can be set to pixmaps with this message. The
3771 <p>
3775 <b id="SCI_MARKERDEFINERGBAIMAGE">SCI_MARKERDEFINERGBAIMAGE(int markerNumber, const char *pixels)</b><br />
3776 Markers can be set to translucent pixmaps with this message. The
3780 <p>A scale factor in percent may be set with <code>SCI_RGBAIMAGESETSCALE</code>. This is useful on OS X with
3781 a retina display where each display unit is 2 pixels: use a factor of 200 so that each image pixel is displayed using a screen pixel.
3782 The default scale, 100, will stretch each image pixel to cover 4 screen pixels on a retina display.</p>
3794 These two messages set the foreground and background colour of a marker number.<br />
3795 <b id="SCI_MARKERSETBACKSELECTED">SCI_MARKERSETBACKSELECTED(int markerNumber, int <a class="jump"
3797 This message sets the highlight background colour of a marker number when its folding block is selected. The default colour is #FF0000.</p>
3799 This message allows to enable/disable the highlight folding block when it is selected. (i.e. block that contains the caret)</p>
3802 When markers are drawn in the content area, either because there is no margin for them or
3803 they are of <code>SC_MARK_BACKGROUND</code> or <code>SC_MARK_UNDERLINE</code> types, they may be drawn translucently by
3804 setting an alpha value.</p>
3808 this fails (illegal line number, out of memory) or it returns a marker handle number that
3813 based on its handle. The message does not check the value of markerNumber, nor does it
3814 check if the line already contains the marker.</p>
3817 This message can add one or more markers to a line with a single call, specified in the same "one-bit-per-marker" 32-bit integer format returned by
3819 (and used by the mask-based marker search functions
3822 As with
3824 to see if any of the markers are already present on the targeted line.</p>
3827 This searches the given line number for the given marker number and deletes it if it is
3828 present. If you added the same marker more than once to the line, this will delete one copy
3829 each time it is used. If you pass in a marker number of -1, all markers are deleted from the
3830 line.</p>
3833 This removes markers of the given number from all lines. If markerNumber is -1, it deletes all
3834 markers from all lines.</p>
3842 These messages search efficiently for lines that include a given set of markers. The search
3845 (<code>SCI_MARKERPREVIOUS</code>). The <code>markerMask</code> argument should have one bit set
3846 for each marker you wish to find. Set bit 0 to find marker 0, bit 1 for marker 1 and so on. The
3847 message returns the line number of the first line that contains one of the markers in
3853 the document for the marker with this handle and returns the line number that contains it or -1
3854 if it is not found.</p>
3859 the document for the marker with this handle and deletes the marker if it is found.</p>
3863 <p>Indicators are used to display additional information over the top of styling.
3864 They can be used to show, for example, syntax errors, deprecated names and bad indentation
3865 by drawing underlines under text or boxes around text.</p>
3867 <p>Indicators may be displayed as simple underlines, squiggly underlines, a
3868 line of small 'T' shapes, a line of diagonal hatching, a strike-out or a rectangle around the text.</p>
3871 indicators. They all use an <code>indicatorNumber</code> argument in the range 0 to INDIC_MAX(31)
3872 to set the indicator to style. To prevent interference the set of indicators is divided up into a range for use
3876 <p>Originally, Scintilla used a different technique for indicators but this
3879 While both techniques were supported, the term "modern indicators" was used for the
3880 newer implementation.</p>
3883 indicatorStyle)</a><br />
3886 colour)</a><br />
3888 <a class="message" href="#SCI_INDICSETALPHA">SCI_INDICSETALPHA(int indicatorNumber, int alpha)</a><br />
3890 <a class="message" href="#SCI_INDICSETOUTLINEALPHA">SCI_INDICSETOUTLINEALPHA(int indicatorNumber, int alpha)</a><br />
3891 <a class="message" href="#SCI_INDICGETOUTLINEALPHA">SCI_INDICGETOUTLINEALPHA(int indicatorNumber)</a><br />
3892 <a class="message" href="#SCI_INDICSETUNDER">SCI_INDICSETUNDER(int indicatorNumber, bool under)</a><br />
3895 <a class="message" href="#SCI_SETINDICATORCURRENT">SCI_SETINDICATORCURRENT(int indicator)</a><br />
3899 <a class="message" href="#SCI_INDICATORFILLRANGE">SCI_INDICATORFILLRANGE(int position, int fillLength)</a><br />
3900 <a class="message" href="#SCI_INDICATORCLEARRANGE">SCI_INDICATORCLEARRANGE(int position, int clearLength)</a><br />
3902 <a class="message" href="#SCI_INDICATORVALUEAT">SCI_INDICATORVALUEAT(int indicator, int position)</a><br />
3903 <a class="message" href="#SCI_INDICATORSTART">SCI_INDICATORSTART(int indicator, int position)</a><br />
3904 <a class="message" href="#SCI_INDICATOREND">SCI_INDICATOREND(int indicator, int position)</a><br />
3906 <a class="message" href="#SCI_FINDINDICATORSHOW">SCI_FINDINDICATORSHOW(int start, int end)</a><br />
3907 <a class="message" href="#SCI_FINDINDICATORFLASH">SCI_FINDINDICATORFLASH(int start, int end)</a><br />
3909 </code>
3912 indicatorStyle)</b><br />
3914 These two messages set and get the style for a particular indicator. The indicator styles
3915 currently available are:<br />
3920 <tbody>
3921 <tr>
3927 </tr>
3928 </tbody>
3931 <tr>
3937 </tr>
3939 <tr>
3945 </tr>
3947 <tr>
3953 </tr>
3955 <tr>
3961 </tr>
3963 <tr>
3969 </tr>
3971 <tr>
3977 </tr>
3979 <tr>
3985 </tr>
3987 <tr>
3992 <td>A rectangle with rounded corners around the text using translucent drawing with the
3993 interior usually more transparent than the border. You can use
3996 to control the alpha transparency values. The default alpha values are 30 for fill colour and 50 for outline colour.</td>
3997 </tr>
3999 <tr>
4004 <td>A rectangle around the text using translucent drawing with the
4005 interior usually more transparent than the border. You can use
4008 to control the alpha transparency values. The default alpha values are 30 for fill colour and 50 for outline colour.</td>
4009 </tr>
4011 <tr>
4017 </tr>
4019 <tr>
4025 </tr>
4027 <tr>
4033 so will fit under small fonts.</td>
4034 </tr>
4036 <tr>
4041 <td>A dotted rectangle around the text using translucent drawing.
4042 Translucency alternates between the alpha and outline alpha settings with the top-left pixel using the alpha setting.
4045 control the alpha transparency values. The default values are 30 for alpha and 50 for outline alpha.
4047 </tr>
4049 <tr>
4055 as a series of line segments for performance.
4058 </tr>
4060 <tr>
4065 <td>A 2-pixel thick underline located at the bottom of the line to try to avoid touching the character base.
4066 Each side is inset 1 pixel so that different indicators in this style covering a range appear isolated.
4067 This is similar to an appearance used for Asian language input composition.</td>
4068 </tr>
4070 </tbody>
4071 </table>
4078 <p><b id="SCI_INDICSETFORE">SCI_INDICSETFORE(int indicatorNumber, int <a class="jump" href="#colour">colour</a>)</b><br />
4080 These two messages set and get the colour used to draw an indicator. The default indicator
4081 colours are equivalent to:<br />
4088 These two messages set and get the alpha transparency used for drawing the
4089 fill colour of the INDIC_ROUNDBOX and INDIC_STRAIGHTBOX rectangle. The alpha value can range from
4091 </p>
4093 <p><b id="SCI_INDICSETOUTLINEALPHA">SCI_INDICSETOUTLINEALPHA(int indicatorNumber, int alpha)</b><br />
4095 These two messages set and get the alpha transparency used for drawing the
4096 outline colour of the INDIC_ROUNDBOX and INDIC_STRAIGHTBOX rectangle. The alpha value can range from
4098 </p>
4102 These two messages set and get whether an indicator is drawn under text or over(default).
4103 Drawing under text works only for indicators when <a class="message" href="#SCI_SETTWOPHASEDRAW">two phase drawing</a>
4104 is enabled.</p>
4106 <p>Indicators are stored in a format similar to run length encoding which is efficient in both
4107 speed and storage for sparse information.</p>
4108 <p>An indicator may store different values for each range but currently all values are drawn the same.
4109 In the future, it may be possible to draw different values in different styles.</p>
4110 <p>
4113 These two messages set and get the indicator that will be affected by calls to
4114 <a class="message" href="#SCI_INDICATORFILLRANGE">SCI_INDICATORFILLRANGE(int position, int fillLength)</a> and
4115 <a class="message" href="#SCI_INDICATORCLEARRANGE">SCI_INDICATORCLEARRANGE(int position, int clearLength)</a>.
4116 </p>
4118 <p>
4121 These two messages set and get the value that will be set by calls to
4123 </p>
4125 <p>
4127 <b id="SCI_INDICATORCLEARRANGE">SCI_INDICATORCLEARRANGE(int position, int clearLength)</b><br />
4128 These two messages fill or clear a range for the current indicator.
4130 the current value.
4131 </p>
4133 <p>
4135 Retrieve a bitmap value representing which indicators are non-zero at a position.
4136 </p>
4138 <p>
4140 Retrieve the value of a particular indicator at a position.
4141 </p>
4143 <p>
4146 Find the start or end of a range with one value from a position within the range.
4147 Can be used to iterate through the document to discover all the indicator positions.
4148 </p>
4152 <p>On OS X search matches are highlighted with an animated gold rounded rectangle.
4153 The indicator shows, then briefly grows 25% and shrinks to the original size to draw the user's attention.
4154 While this feature is currently only implemented on OS X, it may be implemented on other platforms
4155 in the future.</p>
4159 These two messages show and animate the find indicator. The indicator remains visible with
4162 <code>SCI_FINDINDICATORSHOW</code> behaves similarly to the OS X TextEdit and Safari applications
4163 and is best suited to editing documentation where the search target is often a word.
4165 where the match will often be located next to operators which would otherwise be hidden under the indicator's
4166 padding.
4167 </p>
4170 This message hides the find indicator.
4171 </p>
4173 <p>Earlier versions of Scintilla allowed <a href="#StyleByteIndicators">partitioning style bytes</a>
4174 between style numbers and indicators and provided APIs for setting and querying this.</p>
4179 <p>Autocompletion displays a list box showing likely identifiers based upon the user's typing.
4180 The user chooses the currently selected item by pressing the tab character or another character
4182 Autocompletion is triggered by your application. For example, in C if you detect that the user
4184 list of members, you could offer them in an autocompletion list. Alternatively, you could
4185 monitor the user's typing and offer a list of likely items once their typing has narrowed down
4186 the choice to a reasonable list. As yet another alternative, you could define a key code to
4187 activate the list.</p>
4189 <p>When the user makes a selection from the list the container is sent a <code><a class="message"
4191 href="#Notifications">notification message</a>. On return from the notification Scintilla will insert
4192 the selected text unless the autocompletion list has been cancelled, for example by the container sending
4195 <p>To make use of autocompletion you must monitor each character added to the document. See
4198 *list)</a><br />
4204 *chars)</a><br />
4206 separator)</a><br />
4209 *select)</a><br />
4212 char *text)</a><br />
4214 cancel)</a><br />
4217 *chars)</a><br />
4219 chooseSingle)</a><br />
4222 ignoreCase)</a><br />
4224 <a class="message" href="#SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR(int behaviour)</a><br />
4225 <a class="message" href="#SCI_AUTOCGETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCGETCASEINSENSITIVEBEHAVIOUR</a><br />
4233 dropRestOfWord)</a><br />
4235 <a class="message" href="#SCI_REGISTERIMAGE">SCI_REGISTERIMAGE(int type, const char *xpmData)</a><br />
4236 <a class="message" href="#SCI_REGISTERRGBAIMAGE">SCI_REGISTERRGBAIMAGE(int type, const char *pixels)</a><br />
4238 <a class="message" href="#SCI_AUTOCSETTYPESEPARATOR">SCI_AUTOCSETTYPESEPARATOR(char separatorCharacter)</a><br />
4242 <a class="message" href="#SCI_AUTOCSETMAXWIDTH">SCI_AUTOCSETMAXWIDTH(int characterCount)</a><br />
4244 </code>
4249 separator characters. The initial separator character is a space but this can be set or got
4254 <p>With default settings, the list of words should be in sorted order.
4255 If set to ignore case mode with <a class="message" href="#SCI_AUTOCSETIGNORECASE"><code>SCI_AUTOCSETIGNORECASE</code></a>, then
4256 strings are matched after being converted to upper case. One result of this is that the list
4257 should be sorted with the punctuation characters '[', '\', ']', '^', '_', and '`' sorted after
4258 letters.
4259 Alternative handling of list order may be specified with <a class="message" href="#SCI_AUTOCSETORDER">SCI_AUTOCSETORDER</a>
4260 </p>
4263 This message cancels any displayed autocompletion list. When in autocompletion mode, the list
4264 should disappear when the user types a character that can not be part of the autocompletion,
4265 such as '.', '(' or '[' when typing an identifier. A set of characters that will cancel
4270 This message returns non-zero if there is an active autocompletion list and zero if there is
4271 not.</p>
4275 of the list.</p>
4278 This message triggers autocompletion. This has the same effect as the tab key.</p>
4282 automatically cancel the autocompletion list. When you start the editor, this list is
4283 empty.</p>
4287 These two messages set and get the separator character used to separate words in the
4292 This message selects an item in the autocompletion list. It searches the list of words for the
4293 first that matches <code>select</code>. By default, comparisons are case sensitive, but you can
4298 item is found, it is selected. If the item is not found, the autocompletion list closes if
4303 <p><b id="SCI_AUTOCGETCURRENTTEXT">SCI_AUTOCGETCURRENTTEXT(<unused>, char *text)</b><br />
4304 This message retrieves the current selected text in the autocompletion list. Normally the
4306 is used instead.</p>
4308 <p>The value is copied to the <code>text</code> buffer, returning the length (not including the
4316 The default behaviour is for the list to be cancelled if the caret moves to the location it
4317 was at when the list was displayed. By calling this message with a <code>false</code> argument,
4318 the list is not cancelled until the caret moves at least one character before the word being
4319 completed.</p>
4321 <p><b id="SCI_AUTOCSETFILLUPS">SCI_AUTOCSETFILLUPS(<unused>, const char *chars)</b><br />
4322 If a fillup character is typed with an autocompletion list active, the currently selected item
4323 in the list is added into the document, then the fillup character is added. Common fillup
4324 characters are '(', '[' and '.' but others are possible depending on the language. By default,
4325 no fillup characters are set.</p>
4330 automatically added and no list is displayed. The default is to display the list even if there
4331 is only a single item.</p>
4335 By default, matching of characters to list members is case sensitive. These messages let you
4336 set and get case sensitivity.</p>
4338 <p><b id="SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR">SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR(int behaviour)</b><br />
4340 When autocompletion is set to ignore case (<code>SCI_AUTOCSETIGNORECASE</code>), by default it will
4341 nonetheless select the first list member that matches in a case sensitive way to entered characters.
4342 This corresponds to a behaviour property of <code>SC_CASEINSENSITIVEBEHAVIOUR_RESPECTCASE</code> (0).
4343 If you want autocompletion to ignore case at all, choose <code>SC_CASEINSENSITIVEBEHAVIOUR_IGNORECASE</code> (1).</p>
4347 When autocompleting with multiple selections present, the autocompleted text can go into just the main selection with
4348 <code>SC_MULTIAUTOC_ONCE</code> (0) or into each selection with <code>SC_MULTIAUTOC_EACH</code> (1).
4353 The default setting <code>SC_ORDER_PRESORTED</code> (0) requires that the list be provided in alphabetical sorted order.
4354 </p>
4355 <p>Sorting the list can be done by Scintilla instead of the application with <code>SC_ORDER_PERFORMSORT</code> (1).
4356 This will take additional time.
4357 </p>
4358 <p>Applications that wish to prioritize some values and show the list in order of priority instead
4360 This requires extra processing in <a class="message" href="#SCI_AUTOCSHOW">SCI_AUTOCSHOW</a> to create a sorted index.
4361 </p>
4362 <p>Setting the order should be done before calling <a class="message" href="#SCI_AUTOCSHOW">SCI_AUTOCSHOW</a>.
4363 </p>
4367 By default, the list is cancelled if there are no viable matches (the user has typed
4368 characters that no longer match a list entry). If you want to keep displaying the original
4372 <p><b id="SCI_AUTOCSETDROPRESTOFWORD">SCI_AUTOCSETDROPRESTOFWORD(bool dropRestOfWord)</b><br />
4374 When an item is selected, any word characters following the caret are first erased if
4377 <p>
4384 Autocompletion list items may display an image as well as text. Each image is first registered with an integer
4385 type. Then this integer is included in the text of the list separated by a '?' from the text. For example,
4387 The images are in either the <a class="jump" href="#XPM">XPM format</a> (<code>SCI_REGISTERIMAGE</code>) or
4390 the <a class="message" href="#SCI_RGBAIMAGESETWIDTH"><code>SCI_RGBAIMAGESETWIDTH</code></a> and
4391 <a class="message" href="#SCI_RGBAIMAGESETHEIGHT"><code>SCI_RGBAIMAGESETHEIGHT</code></a> messages.
4392 The set of registered images can be cleared with <code>SCI_CLEARREGISTEREDIMAGES</code> and the '?' separator changed
4394 </p>
4396 <p>
4400 Get or set the maximum number of rows that will be visible in an autocompletion list. If there are more rows in the list, then a vertical
4401 scrollbar is shown. The default is 5.
4402 </p>
4404 <p>
4408 Get or set the maximum width of an autocompletion list expressed as the number of characters in the longest item that will be totally visible.
4409 If zero (the default) then the list's width is calculated to fit the item with the most characters. Any items that cannot be fully displayed within
4410 the available width are indicated by the presence of ellipsis.
4411 </p>
4415 <p>User lists use the same internal mechanisms as autocompletion lists, and all the calls
4416 listed for autocompletion work on them; you cannot display a user list at the same time as an
4417 autocompletion list is active. They differ in the following respects:</p>
4421 effect.<br />
4427 <p>BEWARE: if you have set fillup characters or stop characters, these will still be active
4428 with the user list, and may result in items being selected or the user list cancelled due to
4429 the user typing into the editor.</p>
4434 structure. It must be greater than 0 as this is how Scintilla tells the difference between an
4435 autocompletion list and a user list. If you have different types of list, for example a list of
4437 a selection. </p>
4441 <p>Call tips are small windows displaying the arguments to a function and are displayed after
4442 the user has typed the name of the function. They normally display characters using the font
4443 facename, size and character set defined by
4446 facename, size, foreground and background colours and character set with
4448 This also enables support for Tab characters.
4450 There is some interaction between call tips and autocompletion lists in that showing a
4451 call tip cancels any active autocompletion list, and vice versa.</p>
4455 <p>Call tips can highlight part of the text within them. You could use this to highlight the
4456 current argument to a function by counting the number of commas (or whatever separator your
4458 example of call tip use.</p>
4460 <p>The mouse may be clicked on call tips and this causes a
4462 notification to be sent to the container. Small up and down arrows may be displayed within
4464 for showing that there are overloaded variants of one function name and that the user can
4465 click on the arrows to cycle through the overloads.</p>
4467 <p>Alternatively, call tips can be displayed when you leave the mouse pointer for a while over
4472 the value of a variable, or during editing to give information about the word under the
4473 pointer.</p>
4475 *definition)</a><br />
4479 <a class="message" href="#SCI_CALLTIPSETPOSSTART">SCI_CALLTIPSETPOSSTART(int posStart)</a><br />
4481 highlightEnd)</a><br />
4487 </code>
4490 This message starts the process by displaying the call tip window. If a call tip is already
4491 active, this has no effect.<br />
4493 tip text is aligned to start 1 line below this character unless you have included up and/or
4494 down arrows in the call tip text in which case the tip is aligned to the right-hand edge of
4495 the rightmost arrow. The assumption is that you will start the text with something like
4498 '\n' (Line Feed, ASCII code 10) characters. Do not include '\r' (Carriage Return, ASCII
4500 supported if you set a tabsize with
4502 The position of the caret is remembered here so that the call tip can be cancelled automatically if subsequent deletion
4503 moves the caret before this position.</p>
4506 This message cancels any displayed call tip. Scintilla will also cancel call tips for you if
4507 you use any keyboard commands that are not compatible with editing the argument list of a
4508 function.
4509 Call tips are cancelled if you delete back past the position where the caret was when the tip was triggered.</p>
4516 This message returns or sets the value of the current position when <code>SCI_CALLTIPSHOW</code>
4517 started to display the tip.</p>
4520 This sets the region of the call tips text to display in a highlighted style.
4523 <code>hlEnd</code> must be greater than <code>hlStart</code>; <code>hlEnd-hlStart</code> is the
4524 number of characters to highlight. Highlights can extend over line ends if this is
4525 required.</p>
4527 <p>Unhighlighted text is drawn in a mid grey. Selected text is drawn in a dark blue. The
4528 background is white. These can be changed with
4532 </p>
4535 The background colour of call tips can be set with this message; the default colour is white.
4536 It is not a good idea to set a dark colour as the background as the default colour for normal
4537 calltip text is mid grey and the default colour for highlighted text is dark blue. This also
4541 The colour of call tip text can be set with this message; the default colour is mid grey.
4545 The colour of highlighted call tip text can be set with this message; the default colour
4546 is dark blue.</p>
4551 less than 1, Tab characters are not treated specially. Once this call has been used, the
4552 call tip foreground and background colours are also taken from the style.</p>
4561 <p>To allow the container application to perform any of the actions available to the user with
4562 keyboard, all the keyboard actions are messages. They do not take any parameters. These
4567 <tbody>
4568 <tr>
4576 </tr>
4578 <tr>
4586 </tr>
4588 <tr>
4596 </tr>
4598 <tr>
4604 </tr>
4606 <tr>
4612 </tr>
4614 <tr>
4622 </tr>
4624 <tr>
4632 </tr>
4634 <tr>
4642 </tr>
4644 <tr>
4650 </tr>
4652 <tr>
4660 </tr>
4662 <tr>
4668 </tr>
4670 <tr>
4678 </tr>
4680 <tr>
4686 </tr>
4688 <tr>
4696 </tr>
4698 <tr>
4706 </tr>
4708 <tr>
4714 </tr>
4716 <tr>
4722 </tr>
4725 <tr>
4729 </tr>
4731 <tr>
4735 </tr>
4737 <tr>
4741 </tr>
4743 <tr>
4749 </tr>
4751 <tr>
4757 </tr>
4759 <tr>
4767 </tr>
4769 <tr>
4777 </tr>
4779 <tr>
4787 </tr>
4789 <tr>
4794 </tr>
4796 <tr>
4800 </tr>
4802 <tr>
4806 </tr>
4807 </tbody>
4808 </table>
4813 (and convert regular selection to rectangular one, if any).</p>
4816 capitalisation (aCamelCaseIdentifier) or underscores (an_under_bar_ident).</p>
4820 (ie. just after the indentation) unless it is already there; in this case, it acts as SCI_HOME*.</p>
4823 allow movement to the start or end of display lines as opposed to the normal
4828 They go first to the start / end of the display line, like <code>SCI_[HOME|LINEEND]DISPLAY*</code>,
4829 but if the cursor is already at the point, it goes on to the start or end of the document line,
4831 </p>
4834 or end without changing the selection. These commands match OS X platform conventions for the behaviour of the
4837 </p>
4841 <p>There is a default binding of keys to commands that is defined in the Scintilla source in
4845 command that has no arguments can be mapped). You can change the mapping to suit your own
4846 requirements.</p>
4848 sciCommand)</a><br />
4852 </code>
4855 A key definition contains the key code in the low 16-bits and the key modifiers in the high
4857 <br />
4861 enumeration, which contains:<br />
4864 <code>SCK_INSERT</code>, <code>SCK_LEFT</code>, <code>SCK_MENU</code>, <code>SCK_NEXT</code> (Page Down),
4874 If you are building a table, you might
4879 This assigns the given key definition to a Scintilla command identified by
4880 <code>sciCommand</code>. <code>sciCommand</code> can be any <code>SCI_*</code> command that has
4881 no arguments.</p>
4886 to it.</p>
4889 This command removes all keyboard command mapping by setting an empty mapping table.</p>
4893 action. SCI_NULL ensures that keys do not propagate to the parent window as that may
4894 cause focus to move. If you want the standard platform behaviour use the constant 0 instead.</p>
4899 Clicking the wrong button on the mouse pops up a short default editing menu. This may be
4902 Scintilla window will have the opportunity to handle the message.</p>
4906 <p>Start and stop macro recording mode. In macro recording mode, actions are reported to the
4909 record these actions for future replay.</p>
4913 These two messages turn macro recording on and off.</p>
4918 which can include a printer display surface. Printed output shows text styling as on the
4919 screen, but it hides all margins except a line number margin. All special marker effects are
4920 removed and the selection and caret are hidden.</p>
4922 <p>Different platforms use different display surface ID types to print on. On Windows, these are
4927 *pfr)</a><br />
4929 magnification)</a><br />
4935 </code>
4938 This call renders a range of text into a device context. If you use
4939 this for printing, you will probably want to arrange a page header and footer; Scintilla does
4941 example. Each use of this message renders a range of text into a rectangular area and returns
4942 the position in the document of the next character to print.</p>
4945 (for example, if you use this with MFC you will need to paginate in
4947 <pre>
4948 struct Sci_Rectangle { int left; int top; int right; int bottom; };
4950 struct Sci_RangeToFormat {
4951 Sci_SurfaceID hdc; // The Surface ID we print to
4952 Sci_SurfaceID hdcTarget; // The Surface ID we use for measuring (may be same as hdc)
4953 Sci_Rectangle rc; // Rectangle in which to print
4954 Sci_Rectangle rcPage; // Physically printable page size
4955 Sci_CharacterRange chrg; // Range of characters to print
4956 };
4957 </pre>
4959 <p>On Windows, <code>hdc</code> and <code>hdcTarget</code> should both be set to the device context handle
4960 of the output device (usually a printer). If you print to a metafile these will not be the same
4961 as Windows metafiles (unlike extended metafiles) do not implement the full API for returning
4966 rectangle defined by rcPage).<br />
4968 position of characters to output. All of each line within this character range is drawn.</p>
4970 <p>On Cocoa, the surface IDs for printing (<code>bDraw=1</code>) should be the graphics port of the current context
4971 (<code>(CGContextRef) [[NSGraphicsContext currentContext] graphicsPort]</code>) when the view's drawRect method is called.
4973 to a bitmap context (created with <code>CGBitmapContextCreate</code>) to avoid runtime warnings.</p>
4975 <p>On GTK+, the surface IDs to use can be found from the printing context with
4979 position of characters to output. All of each line within this character range is drawn.</p>
4981 <p>When printing, the most tedious part is always working out what the margins should be to
4982 allow for the non-printable area of the paper and printing a header and footer. If you look at
4983 the printing code in SciTE, you will find that most of it is taken up with this. The loop that
4984 causes Scintilla to render text is quite simple if you strip out all the margin, non-printable
4985 area, header and footer code.</p>
4996 These two messages set and get the method used to render coloured text on a printer that is
4997 probably using white paper. It is especially important to consider the treatment of colour if
4998 you use a dark or black screen background. Printing white on black uses up toner and ink very
4999 many times faster than the other way around. You can set the mode to one of:</p>
5002 <tbody>
5003 <tr>
5009 </tr>
5010 </tbody>
5013 <tr>
5019 </tr>
5021 <tr>
5026 <td>If you use a dark screen background this saves ink by inverting the light value of
5027 all colours and printing on a white background.</td>
5028 </tr>
5030 <tr>
5036 </tr>
5038 <tr>
5044 </tr>
5046 <tr>
5051 <td>Everything prints in its own colour on a white background except that line numbers
5052 use their own background colour.</td>
5053 </tr>
5054 </tbody>
5055 </table>
5064 generates one line of output and the line is truncated if it is too long to fit
5065 into the print area.<br />
5067 white space or style changes although if a word is longer than a line, it will be wrapped before
5070 between words.</p>
5076 <a class="message" href="#SCI_GETRANGEPOINTER">SCI_GETRANGEPOINTER(int position, int rangeLength)</a><br />
5078 </code>
5080 <p>On Windows, the message-passing scheme used to communicate between the container and
5081 Scintilla is mediated by the operating system <code>SendMessage</code> function and can lead to
5082 bad performance when calling intensively. To avoid this overhead, Scintilla provides messages
5083 that allow you to call the Scintilla message function directly. The code to do this in C/C++ is
5084 of the form:</p>
5085 <pre>
5086 #include "Scintilla.h"
5090 // now a wrapper to call Scintilla directly
5091 sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
5092 return pSciMsg(pSciWndData, iMessage, wParam, lParam);
5093 }
5094 </pre>
5098 the Scintilla window.</p>
5100 <p>While faster, this direct calling will cause problems if performed from a different thread
5101 to the native thread of the Scintilla window in which case <code>SendMessage(hSciWnd, SCI_*,
5110 pointer.</p>
5113 This message returns the address of the function to call to handle Scintilla messages without
5114 the overhead of passing through the Windows messaging system. You need only call this once,
5115 regardless of the number of Scintilla windows you create.</p>
5118 This returns a pointer to data that identifies which Scintilla window is in use. You must call
5119 this once for each Scintilla window you create. When you call the direct function, you must
5120 pass in the direct pointer associated with the target window.</p>
5125 Grant temporary direct read-only access to the memory used by Scintilla to store
5126 the document.</p>
5128 text of the document is stored consecutively
5129 and ensure there is a NUL character after the text, then returns a pointer to the first character.
5130 Applications may then pass this to a function that accepts a character pointer such as a regular
5131 expression search or a parser. The pointer should <em>not</em> be written to as that may desynchronize
5132 the internal state of Scintilla.</p>
5133 <p>Since any action in Scintilla may change its internal state
5134 this pointer becomes invalid after any call or by allowing user interface activity. The application
5135 should reacquire the pointer after making any call to Scintilla or performing any user-interface calls such
5136 as modifying a progress indicator.</p>
5137 <p>This call takes similar time to inserting a character at the end of the document and this may
5138 include moving the document contents. Specifically, all the characters after the document gap
5139 are moved to before the gap. This compacted state should persist over calls and user interface
5140 actions that do not change the document contents so reacquiring the pointer afterwards is very
5141 quick. If this call is used to implement a global replace operation, then each replacement will
5143 each replacement then the operation will become O(n^2) rather than O(n). Instead, all
5144 matches should be found and remembered, then all the replacements performed.</p>
5147 range requested. The gap is not moved unless it is within the requested range so this call
5149 This can be used by application code that is able to act on blocks of text or ranges of lines.</p>
5153 with a range that contains the gap and consequent costs of moving the gap.</p>
5157 <p>A Scintilla window and the document that it displays are separate entities. When you create
5158 a new window, you also create a new, empty document. Each document has a reference count that
5159 is initially set to 1. The document also has a list of the Scintilla windows that are linked to
5160 it so when any window changes the document, all other windows in which it appears are notified
5161 to cause them to update. The system is arranged in this way so that you can work with many
5162 documents in a single Scintilla window and so you can display a single document in multiple
5163 windows (for use with splitter windows).</p>
5165 <p>Although these messages use <code>document *pDoc</code>, to ensure compatibility with future
5167 is, you can use and store the pointer as described in this section but you should not
5168 dereference it.</p>
5171 *pDoc)</a><br />
5174 *pDoc)</a><br />
5176 *pDoc)</a><br />
5177 </code>
5180 This returns a pointer to the document currently in use by the window. It has no other
5181 effect.</p>
5184 This message does the following:<br />
5190 window.<br />
5194 This message creates a new, empty document and returns a pointer to it. This document is not
5195 selected into the editor and starts with a reference count of 1. This means that you have
5196 ownership of it and must either reduce its reference count by 1 after using
5199 application to avoid memory leaks.</p>
5202 This increases the reference count of a document by 1. If you want to replace the current
5203 document in the Scintilla window and take ownership of the current document, for example if you
5204 are editing many documents in one window, do the following:<br />
5214 must point at a document that still exists. If you call this on a document with a reference
5215 count of 1 that is still attached to a Scintilla window, bad things will happen. To keep the
5221 <p>To ensure a responsive user interface, applications may decide to load and save documents using a separate thread
5222 from the user interface.</p>
5226 <p>An application can load all of a file into a buffer it allocates on a background thread and then add the data in that buffer
5227 into a Scintilla document on the user interface thread. That technique uses extra memory to store a complete copy of the
5228 file and also means that the time that Scintilla takes to perform initial line end discovery blocks the user interface.</p>
5230 <p>To avoid these issues, a loader object may be created and used to load the file. The loader object supports the ILoader interface.</p>
5233 Create an object that supports the <code>ILoader</code> interface which can be used to load data and then
5234 be turned into a Scintilla document object for attachment to a view object.
5235 The <code>bytes</code> argument determines the initial memory allocation for the document as it is more efficient
5236 to allocate once rather than rely on the buffer growing as data is added.
5242 <span class="S5">class</span><span class="S0"> </span>ILoader<span class="S0"> </span><span class="S10">{</span><br />
5244 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>Release<span class="S10">()</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
5245 <span class="S0"> </span><span class="S2">// Returns a status code from SC_STATUS_*</span><br />
5246 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>AddData<span class="S10">(</span><span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>data<span class="S10">,</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>length<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
5247 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">void</span><span class="S0"> </span><span class="S10">*</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>ConvertToDocument<span class="S10">()</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
5249 </div>
5251 <p>The application should call the <code>AddData</code> method with each block of data read from the file.
5252 <code>AddData</code> will return SC_STATUS_OK unless a failure, such as memory exhaustion occurs.
5253 If a failure occurs in <code>AddData</code> or in a file reading call then loading can be abandoned and the loader released with
5255 When the whole file has been read, the <code>ConvertToDocument</code> method should be called to produce a Scintilla
5256 document pointer which can be used in the same way as a document pointer returned from
5262 <p>An application that wants to save in the background should lock the document with <code>SCI_SETREADONLY(1)</code>
5263 to prevent modifications and retrieve a pointer to the unified document contents with
5265 The buffer of a locked document will not move so the pointer is valid until the application calls <code>SCI_SETREADONLY(0)</code>.</p>
5267 <p>If the user tries to performs a modification while the document is locked then a <code><a class="message"
5268 href="#SCN_MODIFYATTEMPTRO">SCN_MODIFYATTEMPTRO</a></code> notification is sent to the application.
5269 The application may then decide to ignore the modification or to terminate the background saving thread and reenable
5270 modification before returning from the notification.</p>
5274 <p>The fundamental operation in folding is making lines invisible or visible. Line visibility
5275 is a property of the view rather than the document so each view may be displaying a different
5276 set of lines. From the point of view of the user, lines are hidden and displayed using fold
5277 points. Generally, the fold points of a document are based on the hierarchical structure of the
5278 document contents. In Python, the hierarchy is determined by indentation and in C++ by brace
5279 characters. This hierarchy can be represented within a Scintilla document object by attaching a
5280 numeric "fold level" to each line. The fold level is most easily set by a lexer, but you can
5281 also set it with messages.</p>
5283 <p>It is up to your code to set the connection between user actions and folding and unfolding.
5284 The best way to see how this is done is to search the SciTE source code for the messages used
5285 in this section of the documentation and see how they are used. You will also need to use
5286 markers and a folding margin to complete your folding implementation.
5290 docLine)</a><br />
5292 displayLine)</a><br />
5299 <a class="message" href="#SCI_SETAUTOMATICFOLD">SCI_SETAUTOMATICFOLD(int automaticFold)</a><br />
5305 expanded)</a><br />
5307 <a class="message" href="#SCI_CONTRACTEDFOLDNEXT">SCI_CONTRACTEDFOLDNEXT(int lineStart)</a><br />
5312 <a class="message" href="#SCI_EXPANDCHILDREN">SCI_EXPANDCHILDREN(int line, int level)</a><br />
5315 line)</a><br />
5316 </code>
5319 When some lines are hidden and/or annotations are displayed, then a particular line in the
5320 document may be displayed at a
5321 different position to its document position. If no lines are hidden and there are no annotations,
5322 this message returns
5323 <code>docLine</code>. Otherwise, this returns the display line (counting the very first visible
5324 line as 0). The display line of an invisible line is the same as the previous visible line. The
5325 display line number of the first line in the document is 0. If lines are hidden and
5327 Lines can occupy more than one display line if they wrap.</p>
5330 When some lines are hidden and/or annotations are displayed, then a particular line in the
5331 document may be displayed at a
5332 different position to its document position. This message returns the document line number that
5333 corresponds to a display line (counting the display line of the first line in the document as
5336 is the number of lines in the document.</p>
5342 The first two messages mark a range of lines as visible or invisible and then redraw the
5343 display.
5345 visible and 0 if it is not visible.
5347 if some lines are hidden.
5348 These messages have no effect on fold levels or fold
5349 flags. The first line can not be hidden.</p>
5353 These two messages set and get a 32-bit value that contains the fold level of a line and some
5354 flags associated with folding. The fold level is a number in the range 0 to
5357 two addition flag bits. <code>SC_FOLDLEVELWHITEFLAG</code> indicates that the line is blank and
5358 allows it to be treated slightly different then its level may indicate. For example, blank
5359 lines should generally not be fold points and will be considered part of the preceding section even though
5360 they may have a lesser fold level.
5362 the line is a header (fold point).</p>
5365 of a line. Likewise, use <code>SCI_GETFOLDLEVEL(line) & SC_FOLDLEVEL*FLAG</code> to get the
5366 state of the flags. To set the fold level you must or in the associated flags. For instance, to
5371 to handle user folding requests. If you do change the fold levels, the folding margin will
5372 update to match your changes.
5375 In addition to showing markers in the folding margin, you can indicate folds to the user by
5376 drawing lines in the text area. The lines are drawn in the foreground colour set for <a
5379 </p>
5382 <tbody>
5383 <tr>
5387 </tr>
5388 </tbody>
5391 <tr>
5395 </tr>
5397 <tr>
5402 </tr>
5404 <tr>
5409 </tr>
5411 <tr>
5416 </tr>
5418 <tr>
5423 </tr>
5425 <tr>
5430 folding. The appearance of this feature may change in the future.</td>
5431 </tr>
5433 <tr>
5437 <td align="left">display hexadecimal line state in line margin to aid debugging of lexing and folding.
5439 </tr>
5440 </tbody>
5441 </table>
5451 state.</p>
5460 Each fold point may be either expanded, displaying all its child lines, or contracted, hiding
5461 all the child lines. This message toggles the folding state of the given line as long as it has
5463 all the lines that depend on the line. The display updates after this message.</p>
5467 These messages set and get the expanded state of a single line. The set message has no effect
5468 on the visible state of the line or any lines that depend on it. It does change the markers in
5469 the folding margin. If you ask for the expansion state of a line that is outside the document,
5472 <p>If you just want to toggle the fold state of one line and handle all the lines that are
5481 These messages provide a higher-level approach to folding instead of setting expanded flags and showing
5482 or hiding individual lines.</p>
5485 <p>To affect the entire document call <code>SCI_FOLDALL</code>. With <code>SC_FOLDACTION_TOGGLE</code>
5486 the first fold header in the document is examined to decide whether to expand or contract.
5487 </p>
5489 <tbody>
5490 <tr>
5494 </tr>
5495 </tbody>
5498 <tr>
5502 </tr>
5504 <tr>
5508 </tr>
5510 <tr>
5514 </tr>
5516 </tbody>
5517 </table>
5518 <p></p>
5521 This is used to respond to a change to a line causing its fold level or whether it is a header to change,
5522 perhaps when adding or removing a '{'.</p>
5523 <p>By the time the container has received the notification that the line has changed,
5524 the fold level has already been set, so the container has to use the previous level in this call
5525 so that any range hidden underneath this line can be shown.
5526 </p>
5530 Instead of implementing all the logic for handling folding in the container, Scintilla can provide behaviour
5531 that is adequate for many applications. The <code>automaticFold</code> argument is a bit set defining
5532 which of the 3 pieces of folding implementation should be enabled. Most applications should be able to use the
5534 flags unless they wish to implement quite different behaviour such as defining their own fold structure.
5536 like to add or change click behaviour such as showing method headers only when Shift+Alt is used in
5537 conjunction with a click.
5538 </p>
5540 <tbody>
5541 <tr>
5545 </tr>
5546 </tbody>
5549 <tr>
5554 </tr>
5556 <tr>
5561 </tr>
5563 <tr>
5568 container.</td>
5569 </tr>
5571 </tbody>
5572 </table>
5575 Search efficiently for lines that are contracted fold headers.
5576 This is useful when saving the user's folding when switching documents or saving folding with a file.
5577 The search starts at line number <code>lineStart</code> and continues forwards to the end of the file.
5578 <code>lineStart</code> is returned if it is a contracted fold header otherwise the next contracted
5583 A line may be hidden because more than one of its parent lines is contracted. Both these
5584 message travels up the fold hierarchy, expanding any contracted folds until they reach the top
5593 <a class="message" href="#SCI_SETWRAPVISUALFLAGS">SCI_SETWRAPVISUALFLAGS(int wrapVisualFlags)</a><br />
5595 <a class="message" href="#SCI_SETWRAPVISUALFLAGSLOCATION">SCI_SETWRAPVISUALFLAGSLOCATION(int wrapVisualFlagsLocation)</a><br />
5596 <a class="message" href="#SCI_GETWRAPVISUALFLAGSLOCATION">SCI_GETWRAPVISUALFLAGSLOCATION</a><br />
5597 <a class="message" href="#SCI_SETWRAPINDENTMODE">SCI_SETWRAPINDENTMODE(int indentMode)</a><br />
5608 </code>
5610 <p>By default, Scintilla does not wrap lines of text. If you enable line wrapping, lines wider
5611 than the window width are continued on the following lines. Lines are broken after space or tab
5612 characters or between runs of different styles. If this is not possible because a word in one
5613 style is wider than the window then the break occurs after the last character that completely
5614 fits on the line. The horizontal scroll bar does not appear when wrap mode is on.</p>
5616 <p>For wrapped lines Scintilla can draw visual flags (little arrows) at end of a a subline of a
5617 wrapped line and at begin of the next subline. These can be enabled individually, but if Scintilla
5618 draws the visual flag at the beginning of the next subline this subline will be indented by one char.
5619 Independent from drawing a visual flag at the begin the subline can have an indention.</p>
5621 <p>Much of the time used by Scintilla is spent on laying out and drawing text. The same text
5622 layout calculations may be performed many times even when the data used in these calculations
5623 does not change. To avoid these unnecessary calculations in some circumstances, the line layout
5624 cache can store the results of the calculations. The cache is invalidated whenever the
5625 underlying data, such as the contents or styling of the document changes. Caching the layout of
5626 the whole document has the most effect, making dynamic line wrap as much as 20 times faster but
5628 line.</p>
5630 <p>Wrapping is not performed immediately there is a change but is delayed until the display
5631 is redrawn. This delay improves performance by allowing a set of changes to be performed
5632 and then wrapped and displayed once. Because of this, some operations may not occur as
5633 expected. If a file is read and the scroll position moved to a particular line in the text,
5634 such as occurs when a container tries to restore a previous editing session, then
5635 the scroll position will have been determined before wrapping so an unexpected range
5636 of text will be displayed. To scroll to the position correctly, delay the scroll until the
5637 wrapping has been performed by waiting for an initial
5647 there is no white space between words.
5648 </p>
5653 You can enable the drawing of visual flags to indicate a line is wrapped. Bits set in
5654 wrapVisualFlags determine which visual flags are drawn.
5655 </p>
5657 <tbody>
5658 <tr>
5662 </tr>
5663 </tbody>
5666 <tr>
5670 </tr>
5672 <tr>
5676 </tr>
5678 <tr>
5683 </td>
5684 </tr>
5686 <tr>
5690 </tr>
5691 </tbody>
5692 </table>
5694 <p><b id="SCI_SETWRAPVISUALFLAGSLOCATION">SCI_SETWRAPVISUALFLAGSLOCATION(int wrapVisualFlagsLocation)</b><br />
5696 You can set whether the visual flags to indicate a line is wrapped are drawn near the border or near the text.
5697 Bits set in wrapVisualFlagsLocation set the location to near the text for the corresponding visual flag.
5698 </p>
5701 <tbody>
5702 <tr>
5706 </tr>
5707 </tbody>
5710 <tr>
5714 </tr>
5716 <tr>
5720 </tr>
5722 <tr>
5726 </tr>
5727 </tbody>
5728 </table>
5732 Wrapped sublines can be indented to the position of their first subline or one more indent level.
5734 The modes are:
5735 </p>
5738 <tbody>
5739 <tr>
5743 </tr>
5744 </tbody>
5747 <tr>
5750 <td>Wrapped sublines aligned to left of window plus amount set by
5752 </tr>
5754 <tr>
5758 </tr>
5760 <tr>
5763 <td>Wrapped sublines are aligned to first subline indent plus one more level of indentation</td>
5764 </tr>
5765 </tbody>
5766 </table>
5771 wrapped lines in terms of the average character width in
5773 There are no limits on indent sizes, but values less than 0 or large values may have
5774 undesirable effects.<br />
5775 The indention of sublines is independent of visual flags, but if
5777 </p>
5784 <tbody>
5785 <tr>
5791 </tr>
5792 </tbody>
5795 <tr>
5801 </tr>
5803 <tr>
5809 </tr>
5811 <tr>
5817 </tr>
5819 <tr>
5825 </tr>
5826 </tbody>
5827 </table>
5831 The position cache stores position information for short runs of text
5832 so that their layout can be determined more quickly if the run recurs.
5836 Split a range of lines indicated by the target into lines that are at most pixelWidth wide.
5837 Splitting occurs on word boundaries wherever possible in a similar manner to line wrapping.
5839 </p>
5842 Join a range of lines indicated by the target into one line by
5843 removing line end characters.
5844 Where this would lead to no space between words, an extra space is inserted.
5845 </p>
5848 Document lines can occupy more than one display line if they wrap and this
5849 returns the number of display lines needed to wrap a document line.</p>
5854 larger or smaller in steps of one point. The displayed point size never goes below 2, whatever
5860 </code>
5870 These messages let you set and get the zoom factor directly. There is no limit set on the
5871 factors you can set, so limiting yourself to -10 to +20 to match the incremental zoom functions
5872 is a good idea.</p>
5876 <p>You can choose to mark lines that exceed a given length by drawing a vertical line or by
5877 colouring the background of characters that exceed the set length.</p>
5884 </code>
5888 These two messages set and get the mode used to display long lines. You can set one of the
5889 values in the table:</p>
5892 <tbody>
5893 <tr>
5899 </tr>
5900 </tbody>
5903 <tr>
5909 </tr>
5911 <tr>
5917 This works well for monospaced fonts. The line is drawn at a position based on the width
5920 your styles use proportional fonts or if your style have varied font sizes or you use a
5921 mixture of bold, italic and normal text.</td>
5922 </tr>
5924 <tr>
5929 <td>The background colour of characters after the column limit is changed to the colour
5931 </tr>
5932 </tbody>
5933 </table>
5937 These messages set and get the column number at which to display the long line marker. When
5938 drawing lines, the column sets a position in units of the width of a space character in
5939 <code>STYLE_DEFAULT</code>. When setting the background colour, the column is a character count
5940 (allowing for tabs) into the line.</p>
5945 These messages set and get the colour of the marker used to show that a line has exceeded the
5951 called the SciLexer version of Scintilla), lexing support for a wide range of programming
5952 languages is included and the messages in this section are supported. If you want to set
5953 styling and fold points for an unsupported language you can either do this in the container or
5954 better still, write your own lexer following the pattern of one of the existing ones.</p>
5956 <p>Scintilla also supports external lexers. These are DLLs (on Windows) or .so modules (on GTK+/Linux) that export three
5961 <a class="message" href="#SCI_SETLEXERLANGUAGE">SCI_SETLEXERLANGUAGE(<unused>, const char
5962 *name)</a><br />
5964 *name)</a><br />
5965 <a class="message" href="#SCI_LOADLEXERLIBRARY">SCI_LOADLEXERLIBRARY(<unused>, const char
5966 *path)</a><br />
5968 <a class="message" href="#SCI_CHANGELEXERSTATE">SCI_CHANGELEXERSTATE(int start, int end)</a><br />
5969 <a class="message" href="#SCI_PROPERTYNAMES">SCI_PROPERTYNAMES(<unused>, char *names)</a><br />
5971 <a class="message" href="#SCI_DESCRIBEPROPERTY">SCI_DESCRIBEPROPERTY(const char *name, char *description)</a><br />
5972 <a class="message" href="#SCI_SETPROPERTY">SCI_SETPROPERTY(const char *key, const char *value)</a><br />
5973 <a class="message" href="#SCI_GETPROPERTY">SCI_GETPROPERTY(const char *key, char *value)</a><br />
5974 <a class="message" href="#SCI_GETPROPERTYEXPANDED">SCI_GETPROPERTYEXPANDED(const char *key, char *value)</a><br />
5975 <a class="message" href="#SCI_GETPROPERTYINT">SCI_GETPROPERTYINT(const char *key, int default)</a><br />
5976 <a class="message" href="#SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions)</a><br />
5978 *keyWordList)</a><br />
5980 <a class="message" href="#SCI_GETSUBSTYLEBASES">SCI_GETSUBSTYLEBASES(<unused>, char *styles)</a><br />
5981 <a class="message" href="#SCI_DISTANCETOSECONDARYSTYLES">SCI_DISTANCETOSECONDARYSTYLES</a><br />
5982 <a class="message" href="#SCI_ALLOCATESUBSTYLES">SCI_ALLOCATESUBSTYLES(int styleBase, int numberStyles)</a><br />
5984 <a class="message" href="#SCI_GETSUBSTYLESSTART">SCI_GETSUBSTYLESSTART(int styleBase)</a><br />
5985 <a class="message" href="#SCI_GETSUBSTYLESLENGTH">SCI_GETSUBSTYLESLENGTH(int styleBase)</a><br />
5986 <a class="message" href="#SCI_GETSTYLEFROMSUBSTYLE">SCI_GETSTYLEFROMSUBSTYLE(int subStyle)</a><br />
5987 <a class="message" href="#SCI_GETPRIMARYSTYLEFROMSTYLE">SCI_GETPRIMARYSTYLEFROMSTYLE(int style)</a><br />
5988 <a class="message" href="#SCI_SETIDENTIFIERS">SCI_SETIDENTIFIERS(int style, const char *identifiers)</a><br />
5994 <code>SCLEX_NULL</code> to select no lexing action and <code>SCLEX_CONTAINER</code> which sends
5995 the <code><a class="message" href="#SCN_STYLENEEDED">SCN_STYLENEEDED</a></code> notification to
5996 the container whenever a range of text needs to be styled. You cannot use the
5998 assigns unused lexer numbers to.</p>
6000 <p><b id="SCI_SETLEXERLANGUAGE">SCI_SETLEXERLANGUAGE(<unused>, const char *name)</b><br />
6002 <code>SCI_SETLEXERLANGUAGE</code> lets you select a lexer by name, and is the only method if you are using an
6003 external lexer or if you have written a lexer module for a language of your own and do not wish
6006 or "Python". To locate the name for the built-in lexers, open the relevant
6012 see if the lexer number changed.</p>
6016 <p><b id="SCI_LOADLEXERLIBRARY">SCI_LOADLEXERLIBRARY(<unused>, const char *path)</b><br />
6017 Load a lexer implemented in a shared library. This is a .so file on GTK+/Linux or a .DLL file on Windows.
6018 </p>
6021 This requests the current lexer or the container (if the lexer is set to
6026 message causes a redraw.</p>
6029 Indicate that the internal state of a lexer has changed over a range and therefore
6030 there may be a need to redraw.</p>
6034 <b id="SCI_DESCRIBEPROPERTY">SCI_DESCRIBEPROPERTY(const char *name, char *description)</b><br />
6035 Information may be retrieved about the properties that can be set for the current lexer.
6036 This information is only available for newer lexers.
6037 <code>SCI_PROPERTYNAMES</code> returns a string with all of the valid properties separated by "\n".
6038 If the lexer does not support this call then an empty string is returned.
6039 Properties may be boolean (<code>SC_TYPE_BOOLEAN</code>), integer (<code>SC_TYPE_INTEGER</code>),
6044 You can communicate settings to lexers with keyword:value string pairs. There is no limit to
6047 there is already a value string associated with the keyword, it is replaced. If you pass a zero
6050 significant.</p>
6054 <code>"$(fold)0"</code>, but when this is accessed, the <code>$(fold)</code> is replaced by the
6057 <p>Currently the "fold" property is defined for most of the lexers to set the fold structure if
6059 setting that determines how to indicate bad indentation. Most keywords have values that are
6061 properties are used.</p>
6063 <p>There is a convention for naming properties used by lexers so that the set of properties can be found by scripts.
6064 Property names should start with "lexer.<lexer>." or "fold.<lexer>." when they apply to one
6067 <p>Applications may discover the set of properties used by searching the source code of lexers for lines that contain
6068 <code>GetProperty</code> and a double quoted string and extract the value of the double quoted string as the property name.
6070 Documentation for the property may be located above the call as a multi-line comment starting with
6074 Lookup a keyword:value pair using the specified key; if found, copy the value to the user-supplied
6075 buffer and return the length (not including the terminating 0). If not found, copy an empty string
6081 <p>If the value argument is 0 then the length that should be allocated to store the value is returned;
6084 <p><b id="SCI_GETPROPERTYEXPANDED">SCI_GETPROPERTYEXPANDED(const char *key, char *value)</b><br />
6085 Lookup a keyword:value pair using the specified key; if found, copy the value to the user-supplied
6086 buffer and return the length (not including the terminating 0). If not found, copy an empty string
6092 <p>If the value argument is 0 then the length that should be allocated to store the value (including any indicated keyword replacement)
6096 Lookup a keyword:value pair using the specified key; if found, interpret the value as an integer and return it.
6097 If not found (or the value is an empty string) then return the supplied default. If the keyword:value pair is found but is not
6104 You can set up to 9 lists of keywords for use by the current lexer.
6108 It is expected that the keywords will be composed of standard ASCII printing characters,
6110 (except common sense).</p>
6112 <p>How these keywords are used is entirely up to the lexer. Some languages, such as HTML may
6113 contain embedded languages, VBScript and JavaScript are common for HTML. For HTML, key word set
6115 is for SGML and DTD keywords. Review the lexer code to see examples of keyword list. A fully
6117 list of strings that describe the uses of the keyword lists.</p>
6120 indentation and set 2 for keywords that cause unindentation. Yet again, you might have a simple
6121 lexer that colours keywords and you could change languages by changing the keywords in set 0.
6122 There is nothing to stop you building your own keyword lists into the lexer, but this means
6123 that the lexer must be rebuilt if more keywords are added.</p>
6125 <p><b id="SCI_DESCRIBEKEYWORDSETS">SCI_DESCRIBEKEYWORDSETS(<unused>, char *descriptions)</b><br />
6126 A description of all of the keyword sets separated by "\n" is returned by <code>SCI_DESCRIBEKEYWORDSETS</code>.</p>
6129 <p>Lexers may support several different sublanguages and each sublanguage may want to style some number of
6130 sets of identifiers (or similar lexemes such as documentation keywords) uniquely. Preallocating a large number for each
6131 purpose would exhaust the number of allowed styles quickly.
6132 This is alleviated by substyles which allow the application to determine how many sets of identifiers to allocate for
6133 each purpose.
6134 Lexers have to explicitly support this feature by implementing the methods in <code>ILexerWithSubStyles</code>.</p>
6140 Returns the distance between a primary style and its corresponding secondary style.</p>
6142 <p><b id="SCI_ALLOCATESUBSTYLES">SCI_ALLOCATESUBSTYLES(int styleBase, int numberStyles)</b><br />
6143 Allocate some number of substyles for a particular base style returning the first substyle number allocated.
6144 Substyles are allocated contiguously.</p>
6147 Free all allocated substyles.</p>
6151 Return the start and length of the substyles allocated for a base style.</p>
6154 For a sub style, return the base style, else return the argument.</p>
6157 For a secondary style, return the primary style, else return the argument.</p>
6161 The prefix feature available with <code>SCI_SETKEYWORDS</code> is not implemented for <code>SCI_SETIDENTIFIERS</code>.</p>
6165 <p>Lexers are programmed as objects that implement the ILexer interface and that interact
6166 with the document they are lexing through the IDocument interface.
6167 Previously lexers were defined by providing lexing and folding functions but creating an object
6168 to handle the interaction of a lexer with a document allows the lexer to store state information that
6169 can be used during lexing. For example a C++ lexer may store a set of preprocessor definitions
6170 or variable declarations and style these depending on their role.</p>
6172 <p>A set of helper classes allows older lexers defined by functions to be used in Scintilla.</p>
6176 <span class="S5">class</span><span class="S0"> </span>ILexer<span class="S0"> </span><span class="S10">{</span><br />
6186 <span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6187 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
6192 <span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6194 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>PropertyType<span class="S10">(</span><span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>name<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6196 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span><span class="S10">*</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>DescribeProperty<span class="S10">(</span><span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>name<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6203 <span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>val<span class="S10">)</span>
6206 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
6207 <span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>
6208 <span class="S10">*</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>DescribeWordListSets<span class="S10">()</span>
6216 <span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>wl<span class="S10">)</span>
6234 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>startPos<span class="S10">,</span>
6249 <span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6251 </div>
6253 <p>
6254 The return values from PropertySet and WordListSet are used to indicate whether the change requires
6255 performing lexing or folding over any of the document. It is the position at which to restart lexing and folding or -1
6256 if the change does not require any extra work on the document.
6257 A simple approach is to return 0 if there is any possibility that a change requires lexing the document again while an
6258 optimisation could be to remember where a setting first affects the document and return that position.
6259 </p>
6261 <p><code>Version</code> returns an enumerated value specifying which version of the interface is implemented:
6262 <code>lvOriginal</code> for <code>ILexer</code> and <code>lvSubStyles</code> for <code>ILexerWithSubStyles</code>.</p>
6267 application and a lexer. An example would be where an application
6268 maintains a single large data structure containing symbolic information
6269 about system headers (like Windows.h) and provides this to the lexer
6270 where it can be applied to each document. This avoids the costs of
6271 constructing the system header information for each document. This is
6275 Previously, lexers were called with a range that started one line before the range that
6276 needs to be folded as this allowed fixing up the last line from the previous folding.
6277 The new approach allows the lexer to decide whether to backtrack or to handle this
6278 more efficiently.</p>
6282 <p>
6283 To allow lexers to report which line ends they support, and to support substyles,
6285 </p>
6288 <span class="S5">class</span><span class="S0"> </span>ILexerWithSubStyles<span class="S0"> </span><span class="S10">:</span><span class="S0"> </span><span class="S5">public</span><span class="S0"> </span>ILexer<span class="S0"> </span><span class="S10">{</span><br />
6290 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>LineEndTypesSupported<span class="S10">()</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6291 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>AllocateSubStyles<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>styleBase<span class="S10">,</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>numberStyles<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6292 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>SubStylesStart<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>styleBase<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6293 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>SubStylesLength<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>styleBase<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6294 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>StyleFromSubStyle<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>subStyle<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6295 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>PrimaryStyleFromStyle<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>style<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6296 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">void</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>FreeSubStyles<span class="S10">()</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6297 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">void</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>SetIdentifiers<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>style<span class="S10">,</span><span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span><span class="S10">*</span>identifiers<span class="S10">)</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6298 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>DistanceToSecondaryStyles<span class="S10">()</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6299 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S5">char</span><span class="S0"> </span><span class="S10">*</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>GetSubStyleBases<span class="S10">()</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6301 </div>
6343 <span class="S0"> </span>LineFromPosition<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>position<span class="S10">)</span>
6344 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
6346 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
6348 <span class="S0"> </span>LineStart<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>line<span class="S10">)</span>
6349 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
6351 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
6353 <span class="S0"> </span>GetLevel<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>line<span class="S10">)</span>
6355 <span class="S5">const</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span>
6357 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span>
6375 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>state<span class="S10">)</span>
6382 <span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>mask<span class="S10">)</span>
6385 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">bool</span>
6389 <span class="S0"> </span><span class="S5">char</span><span class="S0"> </span>style<span class="S10">)</span>
6390 <span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span>
6400 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">void</span>
6402 <span class="S0"> </span>DecorationSetCurrentIndicator<span class="S10">(</span><span class="S5">int</span>
6408 <span class="S0"> </span>DecorationFillRange<span class="S10">(</span><span class="S5">int</span>
6410 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>value<span class="S10">,</span>
6411 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>fillLength<span class="S10">)</span>
6419 <span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>end<span class="S10">)</span>
6428 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">bool</span>
6432 <span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span>
6435 </div>
6437 <p>Scintilla tries to minimize the consequences of modifying text to
6438 only relex and redraw the line of the change where possible. Lexer
6439 objects contain their own private extra state which can affect later
6440 lines. For example, if the C++ lexer is greying out inactive code
6444 the document that it should relex and display more.</p>
6446 <p>For <code>StartStyling</code> the mask argument has no effect. It was used in version 3.4.2 and earlier.</p>
6449 exceptions. Exceptions should not be thrown over build boundaries as the
6450 two sides may be built with different compilers or incompatible
6451 exception options.</p>
6455 <p>
6456 To allow lexers to determine the end position of a line and thus more easily support Unicode line ends
6459 returning <code>INVALID_POSITION</code> for movement beyond the start and end of the document.</p>
6463 not valid Unicode code points.
6465 bytes in the character.
6466 </p>
6469 <span class="S5">class</span><span class="S0"> </span>IDocumentWithLineEnd<span class="S0"> </span><span class="S10">:</span><span class="S0"> </span><span class="S5">public</span><span class="S0"> </span>IDocument<span class="S0"> </span><span class="S10">{</span><br />
6471 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>LineEnd<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>line<span class="S10">)</span><span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6472 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>GetRelativePosition<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>positionStart<span class="S10">,</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>characterOffset<span class="S10">)</span><span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6473 <span class="S0"> </span><span class="S5">virtual</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span>SCI_METHOD<span class="S0"> </span>GetCharacterAndWidth<span class="S10">(</span><span class="S5">int</span><span class="S0"> </span>position<span class="S10">,</span><span class="S0"> </span><span class="S5">int</span><span class="S0"> </span><span class="S10">*</span>pWidth<span class="S10">)</span><span class="S0"> </span><span class="S5">const</span><span class="S0"> </span><span class="S10">=</span><span class="S0"> </span><span class="S4">0</span><span class="S10">;</span><br />
6475 </div>
6481 implemented and thus which methods may be called.</p>
6485 <p>Notifications are sent (fired) from the Scintilla control to its container when an event has
6486 occurred that may interest the container.</p>
6487 <p>Notifications are sent using the
6492 may be set to receive notifications or the <code>ScintillaView</code> class may be subclassed and the
6494 subclass to control whether default handling is performed.</p>
6495 <p>The container is
6498 struct NotifyHeader { // This matches the Win32 NMHDR structure
6499 void *hwndFrom; // environment specific window handle/pointer
6500 uptr_t idFrom; // CtrlID of the window issuing the notification
6501 unsigned int code; // The SCN_* notification code
6502 };
6504 struct SCNotification {
6505 struct Sci_NotifyHeader nmhdr;
6506 int position;
6507 /* SCN_STYLENEEDED, SCN_DOUBLECLICK, SCN_MODIFIED, SCN_MARGINCLICK, */
6508 /* SCN_NEEDSHOWN, SCN_DWELLSTART, SCN_DWELLEND, SCN_CALLTIPCLICK, */
6509 /* SCN_HOTSPOTCLICK, SCN_HOTSPOTDOUBLECLICK, SCN_HOTSPOTRELEASECLICK, */
6510 /* SCN_INDICATORCLICK, SCN_INDICATORRELEASE, */
6511 /* SCN_USERLISTSELECTION, SCN_AUTOCSELECTION */
6513 int ch; /* SCN_CHARADDED, SCN_KEY */
6514 int modifiers;
6515 /* SCN_KEY, SCN_DOUBLECLICK, SCN_HOTSPOTCLICK, SCN_HOTSPOTDOUBLECLICK, */
6516 /* SCN_HOTSPOTRELEASECLICK, SCN_INDICATORCLICK, SCN_INDICATORRELEASE, */
6518 int modificationType; /* SCN_MODIFIED */
6519 const char *text;
6520 /* SCN_MODIFIED, SCN_USERLISTSELECTION, SCN_AUTOCSELECTION, SCN_URIDROPPED */
6522 int length; /* SCN_MODIFIED */
6523 int linesAdded; /* SCN_MODIFIED */
6524 int message; /* SCN_MACRORECORD */
6525 uptr_t wParam; /* SCN_MACRORECORD */
6526 sptr_t lParam; /* SCN_MACRORECORD */
6527 int line; /* SCN_MODIFIED */
6528 int foldLevelNow; /* SCN_MODIFIED */
6529 int foldLevelPrev; /* SCN_MODIFIED */
6530 int margin; /* SCN_MARGINCLICK */
6531 int listType; /* SCN_USERLISTSELECTION */
6532 int x; /* SCN_DWELLSTART, SCN_DWELLEND */
6533 int y; /* SCN_DWELLSTART, SCN_DWELLEND */
6534 int token; /* SCN_MODIFIED with SC_MOD_CONTAINER */
6535 int annotationLinesAdded; /* SCN_MODIFIED with SC_MOD_CHANGEANNOTATION */
6536 int updated; /* SCN_UPDATEUI */
6537 };
6538 </pre>
6540 <p>The notification messages that your container can choose to handle and the messages
6541 associated with them are:</p>
6571 </code>
6574 <code><a class="message" href="#SCI_SETMODEVENTMASK">SCI_SETMODEVENTMASK(int eventMask)</a><br />
6576 <a class="message" href="#SCI_SETMOUSEDWELLTIME">SCI_SETMOUSEDWELLTIME(int milliseconds)</a><br />
6580 </code>
6582 <p>The following additional notifications are sent using a secondary "command" method and should
6583 be avoided in new code as the primary "notification" method provides all the same events with richer
6584 information.
6586 This emulates the Windows Edit control. Only the lower
6593 </code>
6597 These two messages set and get the identifier of the Scintilla instance which is included in notifications as the
6599 When an application creates multiple Scintilla widgets, this allows the source of each notification to be found.
6602 The value should be small, preferably less than 16 bits,
6604 </p>
6609 lexer, you will receive this notification when Scintilla is about to display or print text that
6610 requires styling. You are required to style the text from the line that contains the position
6611 returned by <a class="message" href="#SCI_GETENDSTYLED"><code>SCI_GETENDSTYLED</code></a> up to
6612 the position passed in <code>SCNotification.position</code>. Symbolically, you need code of the
6613 form:</p>
6614 <pre>
6620 MyStyleRoutine(startPos, SCNotification.position);
6621 </pre>
6624 This is sent when the user types an ordinary text character (as opposed to a command
6625 character) that is entered into the text. The container can use this to decide to display a <a
6628 This notification is sent before the character has been styled so processing that depends on
6629 styling should instead be performed in the SCN_UPDATEUI notification.</p>
6633 Sent to the container when the save point is entered or left, allowing the container to
6639 When in read-only mode, this notification is sent to the container if the user tries to change
6640 the text. This can be used to check the document out of a version control system. You can set
6645 Reports all keys pressed but not consumed by Scintilla. Used on GTK+ because of
6646 some problems with keyboard focus and is not sent by the Windows version. <code>SCNotification.ch</code> holds the key code and
6652 The mouse button was double clicked in editor. The <code>position</code> field is set to the text position of the
6658 Either the text or styling of the document has changed or the selection range or scroll position has changed.
6659 Now would be a good time to update any container UI elements that depend on document or view state.
6660 The <code>updated</code> field is set to the bit set of things changed since the previous notification.</p>
6662 <tbody>
6663 <tr>
6670 </tr>
6671 </tbody>
6674 <tr>
6681 </tr>
6683 <tr>
6690 </tr>
6692 <tr>
6699 </tr>
6701 <tr>
6708 </tr>
6709 </tbody>
6710 </table>
6713 This notification is sent when the text or styling of the document changes or is about to
6714 change. You can set a mask for the notifications that are sent to the container with <a
6716 notification structure contains information about what changed, how the change occurred and
6717 whether this changed the number of lines in the document. No modifications may be performed
6719 are:</p>
6722 <tbody>
6723 <tr>
6727 </tr>
6728 </tbody>
6731 <tr>
6735 table.</td>
6736 </tr>
6738 <tr>
6742 </tr>
6744 <tr>
6749 </tr>
6751 <tr>
6756 </tr>
6758 <tr>
6762 information this holds a pointer to the text that is handed to the Undo system, otherwise
6764 </tr>
6766 <tr>
6771 </tr>
6773 <tr>
6777 unused.</td>
6778 </tr>
6780 <tr>
6784 unused.</td>
6785 </tr>
6786 </tbody>
6787 </table>
6792 Undo or Redo of a previous action.</p>
6795 <tbody>
6796 <tr>
6804 </tr>
6805 </tbody>
6808 <tr>
6816 </tr>
6818 <tr>
6826 </tr>
6828 <tr>
6836 </tr>
6838 <tr>
6846 </tr>
6848 <tr>
6856 </tr>
6858 <tr>
6866 </tr>
6868 <tr>
6876 </tr>
6878 <tr>
6886 </tr>
6888 <tr>
6896 </tr>
6898 <tr>
6906 </tr>
6908 <tr>
6916 </tr>
6918 <tr>
6926 </tr>
6928 <tr>
6936 </tr>
6938 <tr>
6943 <td>A line state has changed because <a class="message" href="#SCI_SETLINESTATE">SCI_SETLINESTATE</a>
6944 was called.</td>
6947 </tr>
6949 <tr>
6954 <td>The explicit tab stops on a line have changed because <a class="message" href="#SCI_CLEARTABSTOPS">SCI_CLEARTABSTOPS</a> or
6958 </tr>
6960 <tr>
6968 </tr>
6970 <tr>
6978 </tr>
6980 <tr>
6988 </tr>
6990 <tr>
6995 <td>Text is about to be inserted. The handler may change the text being inserted by calling
6997 No other modifications may be made in this handler.</td>
7000 </tr>
7002 <tr>
7010 </tr>
7012 <tr>
7017 <td>This is set on a SC_PERFORMED_USER action when it is the
7018 first or only step in an undo transaction. This can be used to integrate the Scintilla
7019 undo stack with an undo stack in the container application by adding a Scintilla
7020 action to the container's stack for the currently opened container transaction or
7021 to open a new container transaction if there is no open container transaction.
7022 </td>
7025 </tr>
7027 <tr>
7032 <td>This is set on for actions that the container stored into the undo stack with
7034 </td>
7037 </tr>
7039 <tr>
7048 </tr>
7049 </tbody>
7050 </table>
7055 "command" signal on GTK+ as this is the behaviour of the standard Edit control
7064 These messages set and get an event mask that determines which document change events are
7068 only notifications about changes to text and not styling changes by calling
7074 <code>SC_MOD_CHANGEFOLD</code>, <code>SC_PERFORMED_USER</code>, <code>SC_PERFORMED_UNDO</code>,
7085 behaviour of the standard Edit control. Unfortunately, these codes do not match the Windows Edit
7087 now too late to change the Scintilla codes as clients depend on the current values.</p>
7092 disable macro recording. When enabled, each time a recordable change occurs, the
7097 notification are:</p>
7100 <tbody>
7101 <tr>
7105 </tr>
7106 </tbody>
7109 <tr>
7113 </tr>
7115 <tr>
7119 </tr>
7121 <tr>
7125 </tr>
7126 </tbody>
7127 </table>
7134 used:</p>
7137 <tbody>
7138 <tr>
7142 </tr>
7143 </tbody>
7146 <tr>
7151 at the time of the margin click.</td>
7152 </tr>
7154 <tr>
7158 to the margin click.</td>
7159 </tr>
7161 <tr>
7165 </tr>
7166 </tbody>
7167 </table>
7170 Scintilla has determined that a range of lines that is currently invisible should be made
7171 visible. An example of where this may be needed is if the end of line of a contracted fold
7172 point is deleted. This message is sent to the container in case it wants to make the line
7173 visible in some unusual way such as making the whole document visible. Most containers will
7177 that should be made visible. The container code will be similar to the following code
7178 skeleton:</p>
7179 <pre>
7180 firstLine = SCI_LINEFROMPOSITION(scn.position)
7181 lastLine = SCI_LINEFROMPOSITION(scn.position+scn.length-1)
7182 for line = lineStart to lineEnd do SCI_ENSUREVISIBLE(line) next
7183 </pre>
7186 Painting has just been done. Useful when you want to update some other widgets based on a
7187 change in Scintilla, but want to have the paint occur first to appear more responsive. There is
7195 <tbody>
7196 <tr>
7200 </tr>
7201 </tbody>
7204 <tr>
7209 initiated the list.</td>
7210 </tr>
7212 <tr>
7216 </tr>
7218 <tr>
7222 </tr>
7223 </tbody>
7224 </table>
7225 <br />
7229 Only on the GTK+ version. Indicates that the user has dragged a URI such as a file name or Web
7230 address onto Scintilla. The container could interpret this as a request to open the file. The
7239 key press indicates the dwell is over. Both notifications set the same fields in
7243 <tbody>
7244 <tr>
7248 </tr>
7249 </tbody>
7252 <tr>
7256 mouse pointer was lingering.</td>
7257 </tr>
7259 <tr>
7265 </tr>
7266 </tbody>
7267 </table>
7268 <br />
7272 These two messages set and get the time the mouse must sit still, in milliseconds, to generate
7277 This notification is generated when the user zooms the display using the keyboard or the
7279 notification can be used to recalculate positions, such as the width of the line number margin
7280 to maintain sizes in terms of characters rather than pixels. <code>SCNotification</code> has no
7281 additional information.</p>
7283 <p>
7287 These notifications are generated when the user clicks or double clicks on
7288 text that is in a style with the hotspot attribute set.
7289 This notification can be used to link to variable definitions or web pages.
7295 <p>
7298 These notifications are generated when the user clicks or releases the mouse on
7299 text that has an indicator.
7305 This notification is generated when the user clicks on a calltip.
7306 This notification can be used to display the next function prototype when a
7307 function name is overloaded with different arguments.
7312 The user has selected an item in an <a class="jump" href="#Autocompletion">autocompletion list</a>. The
7313 notification is sent before the selection is inserted. Automatic insertion can be cancelled by sending a
7318 <tbody>
7319 <tr>
7323 </tr>
7324 </tbody>
7327 <tr>
7331 </tr>
7332 <tr>
7336 </tr>
7337 </tbody>
7338 </table>
7342 There is no other information in SCNotification.</p>
7345 The user deleted a character while autocompletion list was active.
7346 There is no other information in SCNotification.</p>
7355 <p>Two formats are supported for images used in margin markers and autocompletion lists, RGBA and XPM.</p>
7360 value for each pixel. It is simpler than
7363 <p>The data is a sequence of 4 byte pixel values starting with the pixels for the top line, with the
7364 leftmost pixel first, then continuing with the pixels for subsequent lines. There is no gap between
7365 lines for alignment reasons.</p>
7367 <p>Each pixel consists of, in order, a red byte, a green byte, a blue byte and an alpha byte.
7368 The colour bytes are not premultiplied by the alpha value. That is, a fully red pixel that is
7371 <p>Since the RGBA pixel data does not include any size information the
7372 width and height must previously been set with the
7374 <a class="message" href="#SCI_RGBAIMAGESETHEIGHT"><code>SCI_RGBAIMAGESETHEIGHT</code></a> messages.</p>
7376 <p>GUI platforms often include functions for reading image file formats like PNG into memory
7377 in the RGBA form or a similar form.
7378 If there is no suitable platform support, the <a href="http://lodev.org/lodepng/">LodePNG and picoPNG</a> libraries are small libraries
7379 for loading and decoding PNG files available under a BSD-style license.</p>
7385 <p>The XPM format is
7387 Scintilla is only able to handle XPM pixmaps that use one character per pixel with no named colours.
7389 <p>There are two forms of data structure used for XPM images, the first "lines form" format is well suited
7390 to embedding an image inside C source code and the "text form" is suited to reading from a file.
7391 In the lines form, an array of strings is used with the first string indicating the dimensions and number of colours
7392 used. This is followed by a string for each colour and that section is followed by the image with one string per line.
7393 The text form contains the same data as one null terminated block formatted as C source code starting
7395 <p>Either format may be used with Scintilla APIs with the bytes at the location pointed to examined
7396 to determine which format: if the bytes start with "/* XPM */" then it is treated as text form,
7397 otherwise it is treated as lines form.</p>
7402 <p>On GTK+, the following functions create a Scintilla widget, communicate with it and allow
7403 resources to be released after all Scintilla widgets have been destroyed.</p>
7405 <a class="message" href="#scintilla_set_id">void scintilla_set_id(ScintillaObject *sci, uptr_t id)</a><br />
7406 <a class="message" href="#scintilla_send_message">sptr_t scintilla_send_message(ScintillaObject *sci,unsigned int iMessage, uptr_t wParam, sptr_t lParam)</a><br />
7407 <a class="message" href="#scintilla_release_resources">void scintilla_release_resources()</a><br />
7408 </code>
7411 Create a new Scintilla widget. The returned pointer can be added to a container and displayed in the same way as other
7412 widgets.</p>
7415 Set the control ID which will be used in the idFrom field of the NotifyHeader structure of all
7416 notifications for this instance.
7419 <p><b id="scintilla_send_message">sptr_t scintilla_send_message(ScintillaObject *sci,unsigned int iMessage, uptr_t wParam, sptr_t lParam)</b><br />
7420 The main entry point allows sending any of the messages described in this document.</p>
7423 Call this to free any remaining resources after all the Scintilla widgets have been destroyed.</p>
7427 <p>Complex new features may be added as 'provisional' to allow further changes to the API.
7428 Provisional features may even be removed if experience shows they are a mistake.</p>
7430 <p>Provisional features are displayed in this document with <span class="provisional">a distinctive background colour</span>.</p>
7432 <p>There are currently no provisional messages.
7436 <p>Some developers may want to only use features that are stable and have graduated from
7437 provisional status. To avoid using provisional messages compile with the symbol
7442 <p>The following messages are currently supported to emulate existing Windows controls, but
7443 they will be removed in future versions of Scintilla. If you use these messages you should
7444 replace them with the Scintilla equivalent.</p>
7445 <pre>
7446 WM_GETTEXT(int length, char *text)
7448 EM_GETLINE(int line, char *text)
7450 EM_SETREADONLY
7452 WM_CUT
7453 WM_COPY
7454 WM_PASTE
7455 WM_CLEAR
7456 WM_UNDO
7457 EM_CANUNDO
7458 EM_EMPTYUNDOBUFFER
7459 WM_GETTEXTLENGTH
7460 EM_GETFIRSTVISIBLELINE
7461 EM_GETLINECOUNT
7462 EM_GETMODIFY
7463 EM_SETMODIFY(bool isModified)
7464 EM_GETRECT(RECT *rect)
7465 EM_GETSEL(int *start, int *end)
7467 EM_SETSEL(int start, int end)
7470 EM_LINEFROMCHAR(int position)
7471 EM_EXLINEFROMCHAR(int position)
7472 EM_LINEINDEX(int line)
7473 EM_LINELENGTH(int position)
7474 EM_SCROLL(int line)
7475 EM_LINESCROLL(int column, int line)
7476 EM_SCROLLCARET()
7477 EM_CANPASTE
7479 EM_POSFROMCHAR(int position, POINT *location)
7480 EM_SELECTIONTYPE
7481 EM_HIDESELECTION(bool hide)
7482 EM_FINDTEXT(int flags, FINDTEXTEX *ft)
7483 EM_FINDTEXTEX(int flags, FINDTEXTEX *ft)
7484 EM_GETMARGINS
7485 EM_SETMARGINS(EC_LEFTMARGIN or EC_RIGHTMARGIN or EC_USEFONTINFO, int val)
7486 EM_FORMATRANGE
7487 </pre>
7489 <p>The following are features that are only included if you define
7491 compatibility you should change them as indicated.</p>
7494 This was used to set a DBCS (Double Byte Character Set) mode on GTK+.
7495 An explicit DBCS code page should be used when calling <a class="message" href="#SCI_SETCODEPAGE">SCI_SETCODEPAGE</a></p>
7499 Scintilla no longer supports palette mode. The last version to support palettes was 2.29.
7500 Any calls to these methods should be removed.</p>
7502 <p>The following are features that should be removed from calling code but are still
7503 defined to avoid breaking callers.</p>
7505 <p id="StyleByteIndicators"><b id="SCI_SETSTYLEBITS">SCI_SETSTYLEBITS(int bits)</b> Deprecated<br />
7508 <code>INDIC0_MASK</code>, <code>INDIC1_MASK</code>, <code>INDIC2_MASK</code>, <code>INDICS_MASK</code> Deprecated<br />
7509 Scintilla no longer supports style byte indicators. The last version to support style byte indicators was 3.4.2.
7510 Any use of these symbols should be removed and replaced with <a href="#Indicators">standard indicators</a>.
7513 </p>
7517 <pre>
7518 EM_GETWORDBREAKPROC EM_GETWORDBREAKPROCEX
7519 EM_SETWORDBREAKPROC EM_SETWORDBREAKPROCEX
7520 EM_GETWORDWRAPMODE EM_SETWORDWRAPMODE
7521 EM_LIMITTEXT EM_EXLIMITTEXT
7522 EM_SETRECT EM_SETRECTNP
7523 EM_FMTLINES
7524 EM_GETHANDLE EM_SETHANDLE
7525 EM_GETPASSWORDCHAR EM_SETPASSWORDCHAR
7526 EM_SETTABSTOPS
7527 EM_FINDWORDBREAK
7528 EM_GETCHARFORMAT EM_SETCHARFORMAT
7529 EM_GETOLEINTERFACE EM_SETOLEINTERFACE
7530 EM_SETOLECALLBACK
7531 EM_GETPARAFORMAT EM_SETPARAFORMAT
7532 EM_PASTESPECIAL
7533 EM_REQUESTRESIZE
7534 EM_GETBKGNDCOLOR EM_SETBKGNDCOLOR
7535 EM_STREAMIN EM_STREAMOUT
7536 EM_GETIMECOLOR EM_SETIMECOLOR
7537 EM_GETIMEOPTIONS EM_SETIMEOPTIONS
7538 EM_GETOPTIONS EM_SETOPTIONS
7539 EM_GETPUNCTUATION EM_SETPUNCTUATION
7540 EM_GETTHUMB
7541 EM_GETEVENTMASK
7542 EM_SETEVENTMASK
7543 EM_DISPLAYBAND
7544 EM_SETTARGETDEVICE
7545 </pre>
7547 <p>Scintilla tries to be a superset of the standard windows Edit and RichEdit controls wherever
7548 that makes sense. As it is not intended for use in a word processor, some edit messages can not
7549 be sensibly handled. Unsupported messages have no effect.</p>
7553 <p>Previous versions of Scintilla allowed indicators to be stord in bits of each style byte.
7555 All uses of style byte indicators should be replaced with <a href="#Indicators">standard indicators</a>.</p>
7559 <p>To build Scintilla or SciTE, see the README file present in both the Scintilla and SciTE
7562 supported. The version of GTK+ installed should be detected automatically.
7564 on the command line.</p>
7568 <p>On Windows, Scintilla is normally used as a dynamic library as a .DLL file. If you want to
7569 link Scintilla directly into your application .EXE or .DLL file, then the
7571 <code>Scintilla_RegisterClasses</code> called. <code>STATIC_BUILD</code> prevents compiling the
7572 <code>DllMain</code> function which will conflict with any <code>DllMain</code> defined in your
7578 <p>Depending on the compiler and linker used, the lexers may be stripped out. This is most
7579 often caused when building a static library. To ensure the lexers are linked in, the
7584 <p>To change the set of lexers in Scintilla, add and remove lexer source files
7586 <code>scripts/LexGen.py</code> script from the <code>scripts</code> directory to update the make files
7588 not have access to Python, you can hand edit <code>Catalogue.cxx</code> in a simple-minded way,
7589 following the patterns of other lexers. The important thing is to include
7595 <p id="AlternativeRegEx">A simple interface provides support for switching the Regular Expressions engine at
7599 to create an instance of your class. You must disable the built-in implementation by defining
7602 </body>
7603 </html>